API Clients

What an API client is

An API client lets another system, such as an integration or a script, log in to the CWS API without using a person's username and password. Each client has its own Client ID and Client Secret, and acts as one CWS user.

Why use one:

  • Changing the user's password does not break the integration.
  • You can give each integration its own user, with only the permissions it needs.
  • You can change the secret or turn a client off without affecting anything else.

API clients are managed by account admins. Store users and portal-only users cannot have API clients, so choose a normal user (usually one made for the integration).

Creating an API client

  1. Go to Admin > Users and open the user the client will act as.
  2. Choose API Clients on the left. It lists the user's clients with their name, Client ID, the end of the secret, whether they are active, when they were last used and when they were created.
  3. Click Add API Client.
  4. Enter a Name that tells you which system uses it, and save.
  5. A window shows the Client ID, the Client Secret and the token URL. Copy the secret now. It cannot be shown again. If you lose it, use New Secret.

To change a client later, click its row. You can change the name, and switch off Active to turn it off.

Permissions

A client acts as its user, so it can do exactly what the user can do in the API, and nothing more. Each API call needs the same permission as the screen that shows the same data: for example, listing work orders needs the same permission as the Workorders list. The identity calls that tell the system who is logged in need no permission.

To limit what an integration can do, give it a user of its own and put that user in a user group with only the permissions the integration needs. A change to the user's permissions applies to the client straight away.

If the user is made inactive or banned, or the account is suspended, the client stops working too.

Getting a token

Send the Client ID and Client Secret to the token URL. Replace youraccount with your account name:

curl -u "CLIENT_ID:CLIENT_SECRET" \
  -d grant_type=client_credentials \
  https://youraccount.cws.app/oauth/token

The reply contains an access_token:

{"access_token":"cwsat_...","token_type":"Bearer","expires_in":3600,"scope":"cws"}

Send it on every API call:

curl -H "Authorization: Bearer cwsat_..." "https://youraccount.cws.app/api/v1/wos?limit=1"

A token lasts one hour (expires_in is in seconds). When it expires, or the API says it has expired, request a new one the same way. Reuse a token until then rather than asking for one per call: token requests are limited per IP address.

You can also send client_id and client_secret as form fields instead of using -u. A scope sent with the request is accepted but changes nothing: every token carries the single scope cws and acts as the client's user.

The older login with a username and password (/api/v1/auth) still works. See the API documentation for all endpoints.

Changing the secret

Open the client and click New Secret. A window shows the new secret once, so copy it.

The old secret stops working at once, and the tokens already issued are cancelled. Update the secret in the other system straight away. Do this whenever a secret may have been seen by someone who should not have it.

Turning a client off or deleting it

  • Turn it off: open the client and untick Active. It cannot get new tokens and its current tokens stop working at once. You can turn it back on later.
  • Delete it: open the client and click Delete. The client and its tokens are removed and cannot be recovered. Anything still using it will be refused.