API tokens allow you to access our platform using your user's specific permissions. These tokens act on your behalf, meaning any API operations performed will be executed with your exact user credentials and access permissions.
For more information you can check our API documentation.
To find your API token / Refresh token navigate to My settings > API tokens:
How long do API tokens last?
Access token — short-lived; it expires after 15 minutes.
Refresh token — valid for 7 days.
There is no non-expiring token or static API key. This is by security design.
How do I keep an integration authenticated?
You don't need to regenerate tokens manually. Every call to the refreshToken mutation returns a new access token and a new refresh token with a fresh 7-day lifetime. As long as your integration refreshes before its current refresh token expires, it stays authenticated indefinitely.
Recommended pattern for automated workflows:
Store both the access token and the refresh token in a secure secret store (for example AWS Secrets Manager, Vault, or your workflow tool's secret store).
Call the Shapes API with the access token in the standard Authorization: Bearer header.
When you get a 401 Unauthorized response — or proactively, shortly before the access token expires — call the refreshToken mutation. It takes no arguments; send the current refresh token in the Refresh-Token header:
mutation { refreshToken { accessToken refreshToken } }Overwrite the stored tokens with the new pair that's returned, then retry the original request.
Use a system user for integrations
Because tokens run with the permissions of the user they belong to, refresh calls will fail if that user is deactivated in Shapes. For automated integrations, create a dedicated system user with its own system permissions role and use that user's tokens. The integration keeps working when team members leave, and it has exactly the permissions it needs — rather than relying on a real employee's personal token. See Permission Levels for an example.
What You Can Do with the API
Reads through the API are broad. Writes are limited to the set of published mutations, and new ones are added over time — the API documentation above is the authoritative list of what is currently available, rather than this article.
Some actions specifically have no API equivalent and have to happen inside Shapes. Approving or denying a time-away booking is one of these: there is no mutation for it today.
Workflow runs can be triggered through the API using the createWorkflowEmployeeAssignments mutation, with the workflows and workflowEmployeeAssignments queries available for managing them — for example, from a button in an external system that starts a request flow for an employee.