Contents
API clients
Updated
by Katy Harrison
You can conveniently set up and manage your own API clients directly in MyWorkplace. You will need to be a Customer admin to use this functionality.
These clients receive OAuth2 credentials, which can be used to obtain tokens to access APIs for MyWorkplace and other Advanced products.
You can find API clients in the Apps menu, under Integrations, or by going to API clients (myworkplace.oneadvanced.com).
On the API clients page, you will see a list of all your existing clients. From this list, you can manage your clients through several actions such as view, edit, delete, and for confidential clients, rotate the secret. You can also add new clients from here.
Creating a new client
- Open the API clients page and click on the + Add client button at the top right.
- Complete at least the mandatory fields:
Name
Grant types
Redirect URLs (if Authorization Code (With PKCE) chosen as grant type)
Owner email
Type
Public is for clients that can't be trusted with secrets such as SPA/progressive web applications.
Confidential is for clients that can be trusted with a secret, typically machine-to-machine integrations.
Grant types
The Client credentials grant type gives a client basic permissions. To call administration APIs, like creating users, a service Role that grants the required permission must be added.
For the Authorization code (with PKCE) grant type, a user will need to login first using a browser (and if the refresh token expires) to authorise the client. Subsequently, the client will be granted the user's permissions. If the user is a customer admin, the client will receive the same permissions.
Clients with the Authorization code (with PKCE) grant type require redirect URLs to be provided. These are used by the system to send the user to the application that requires authorisation and passes any tokens generated. For security reasons the system will NOT allow any wildcard (*) URLS and that http is only supported on “localhost” or “127.0.0.1”.
Owner's details
- Click Add to create the client, then make sure to manage the secrets appropriately.
Managing secrets
Public clients do not have a secret.
For security reasons, secrets are hidden by default. You can view the secret by clicking on the eye icon. You can copy secrets to your clipboard using the Copy button to make it easy to input.
In cases of loss, theft, or to ensure good security practices, the secret can be rotated. This involves generating a new random string as a secret.
To rotate a secret, go to the API clients screen, click on the actions icon and select Rotate secret.
You will need to input the client’s name to confirm the operation, which can't be undone. Once the rotation is successful, the old secret will immediately no longer be usable.
Viewing client details
You can view client details from the API clients screen by clicking the actions icon and selecting View.
You will be able to see the client information, settings, and any necessary URLs for the supported OAuth2 flow to get a bearer token for API calling.
You won't be able to view secrets as they are only shown when a client is added or when the secret is rotated.
Making changes to an existing client
You can make changes to some client information and settings after creation. From the API clients screen, click on the actions icon and select Edit.
If you change the client type from confidential to public, any existing secrets are removed.
If you change the type from public to confidential, you will then have to generate a secret. Go back to the client list, click on the actions icon and select Rotate secret.
Deleting a client
You can delete a client from the API clients screen by clicking more options and selecting Delete. You will need to enter the client’s name for verification. Client removal is immediate and cannot be undone.
