Managing clients

Once granted API access, organisations can manage the credentials for their own API integrations.

API administrators

When you apply for access to RoS APIs, we will ask you to nominate trusted users within your organisation to act as API administrators. They will be able to manage the client credentials used by API integrations to authenticate with RoS APIs on your organisation's behalf.

Because client credentials may allow an API integration to read and write your organisation's data and add charges to your FAS accounts, we advise that only senior staff at your organisation should be given this responsibility.

Normally an API administrator will be the lead of your in-house development team, or the person responsible for liaising with external development teams and API integration providers. Alternatively a senior partner or director can be nominated.

An Online Services user account will be created for each API administrator. When they log in to Online Services, they will see a link to API Client Manager on their homepage.

WarningYou must inform RoS if an API administrator leaves your organisation, so that we can disable their account.

Creating a new client

1. Open API Client Manager and click Create API client.
2. Enter a display name that will help you identify the client and the API integration that will use its credentials.
3. Select permissions to grant the client. The APIs that your organisation has been granted access to will be listed here.
4. If you have granted permission for an API that supports a default FAS number, you will be given the option to select one. Refer to the documentation for each API for further details of this feature.
5. Review the entered details and create the client.
6. A confirmation page will be displayed with the new client's credentials - an ID and secret. This secret will not be displayed again so make a secure note of it.

If your organisation has more than one API integration we strongly recommend creating a separate client for each. This will allow you to change secrets or disable a single client without affecting others. This is especially important if these integrations are built by third parties.

Updating a client

The display name, permissions and (if relevant) default FAS numbers for a client can be updated at any time. Previously granted permissions can be revoked. If the API integration using the client credentials relied on a revoked permission it will stop working.

Managing secrets

Secrets can be added and deleted using the API Client Manager. A client can have up to three secrets, which enables routine changes without breaking integrations using a current secret.

Although secrets do not expire, it is best practice to periodically change them. To do this, add a new secret, update your integration, then delete the old secret.

The first five characters of each secret are displayed to help you identify which one is in use. RoS does not store and cannot recover the rest.

WarningIt is the responsibility of organisations that sign up to use RoS APIs to ensure that API credentials are stored and communicated securely and only shared with trusted developers. If you suspect credentials have been compromised you must delete the secret or disable the client immediately, and notify RoS.

Disabling clients

If you wish to temporarily disable an API integration, you can disable the client it is using. The integration will not be able to fetch new API tokens and any existing tokens will expire within five minutes.

From time to time, RoS may disable a client if it is suspected to be in breach of the API terms and conditions. Organisations cannot re-enable clients that have been disabled by RoS.

Sandbox environment

The sandbox environment is completely independent to production, with no user accounts or client credentials shared between them. No changes you make in sandbox will impact production.

Next steps

Once you have created a client, follow the authentication guide.