Create an API Key

An API key identifies your integration and controls which endpoints it can call. You create keys in the Crewsum app.

You must be signed in as an Administrator or Tenant Admin to manage API keys.

Generate a key

1. Sign in to the Crewsum app at app.crewsum.com. In the sidebar, select Developer > API Keys.

   

2. Select Generate API Key. The New API Key panel opens.

3. In Label, enter a name that tells you what the key is for, such as Operations reporting. The label is optional, but it helps you find the key later.

4. Under Scopes, select each scope that your integration needs. Each scope shows its name, a description, and its scope value, such as clients:read. You must select at least one scope.

   

   See Choose scopes below.

5. Scroll to the bottom of the panel and select Generate Key.

   

6. The panel now shows Your API Key. Select the copy button next to the key, and store the key in a secure place, such as a secrets manager.

   

   You can see the key only once

   Crewsum does not store the full key. After you close this panel, you cannot see the key again. If you lose it, generate a new key and delete the old one.

7. Select Close. The new key appears in the list. The list shows the start of each key, its label, its scopes, and when it was created.

   

API keys start with cs_. Send the full key in the x-api-key header of each request. See Authentication.

Choose scopes

Each endpoint requires exactly one scope, and a key can call an endpoint only if it has that scope. Scopes are matched exactly:

• clients:write does not include clients:read. To list and update clients, select both.
• There are no wildcard or parent scopes.

The endpoint pages in the API Reference show the scope that each endpoint requires. The Scopes page lists every scope.

Select only the scopes that your integration uses. For example, a payroll export that reads approved timesheets needs only timesheets:read.

If a key does not have the required scope, the request fails. See Errors.

Change or revoke a key

You cannot change the scopes or the label of an existing key. To change the scopes:

1. Generate a new key with the scopes you need.
2. Update your integration to use the new key.
3. Delete the old key.

To delete a key, open the … menu in its row and select Delete key. In the Delete API Key dialog, select Delete Key. The key stops working immediately.

Keep your key safe

• Treat the key like a password. Anyone with the key can call the API with its scopes.
• Do not put the key in front-end code, mobile apps, or source control. Call the API only from your server.
• Use a separate key for each integration, so that you can revoke one without affecting the others.
• If a key is exposed, delete it and generate a new one.