Account API
Personal access tokens
Authenticate every request with a personal access token sent as a bearer token.
Bearer tokens
The API uses personal access tokens. Send yours in the Authorization header of every request, together with Accept: application/json.
curl https://cycle.am/api/v1/user \
-H "Authorization: Bearer $CYCLE_API_TOKEN" \
-H "Accept: application/json"A token acts as you. It sees what your account can see, limited to the permissions you gave the token. Requests without a valid token get a 401 error.
Create a token
- Sign in to Cycle. The API tokens page needs a verified email address.
- Open Settings → API tokens.
- Enter a Token name that tells you where the token is used, for example "Deploy script".
- Choose its Permissions. Read is selected by default, and it is the permission every current endpoint needs.
- Click Create token and copy the token right away.
A token looks like 12|Xk3f…. Send the whole string, including the number before the |.
Permissions
Each token carries one or more permissions (abilities). An endpoint checks the token for the ability it needs and answers 403 with Invalid ability provided. when it is missing.
| Permission | Ability | Endpoints that need it |
|---|---|---|
| Read | read | GET /api/v1/user, GET /api/v1/teams, GET /api/v1/teams/{team} |
| Create | create | None yet. Reserved for upcoming endpoints that change data. |
| Update | update | None yet. Reserved for upcoming endpoints that change data. |
| Delete | delete | None yet. Reserved for upcoming endpoints that change data. |
Give each token only the permissions it needs. For everything in v1, that is Read.
Revoking tokens
Tokens do not expire. A token works until you revoke it in Settings → API tokens, and requests made with it fail with 401 from then on.
The same page shows when each token was created and last used, so you can find tokens nobody uses any more.
Keeping tokens safe
- Server side only. Never put a token in browser code, a mobile app or a public repository.
- Use a secret store. Load the token from an environment variable or your secret manager, as the examples do with
CYCLE_API_TOKEN. - One token per integration. You can then revoke one without breaking the others.
Rate limits
Each user account can make 60 requests per minute. The limit is shared by all of the account's tokens. Every response tells you where you stand:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute (60). |
X-RateLimit-Remaining | Requests left in the current minute. |
Retry-After | Only on 429 responses: seconds to wait before retrying. |
X-RateLimit-Reset | Only on 429 responses: Unix timestamp when the limit resets. |
Over the limit, the API answers 429 Too Many Requests. Wait for Retry-After seconds, then try again. See 429 errors.