Skip to content
On this page

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

  1. Sign in to Cycle. The API tokens page needs a verified email address.
  2. Open Settings → API tokens.
  3. Enter a Token name that tells you where the token is used, for example "Deploy script".
  4. Choose its Permissions. Read is selected by default, and it is the permission every current endpoint needs.
  5. Click Create token and copy the token right away.
The token is shown once
Cycle stores only a hash of the token, so it cannot show it to you again. If you lose a token, revoke it and create a new one.

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.

PermissionAbilityEndpoints that need it
ReadreadGET /api/v1/user, GET /api/v1/teams, GET /api/v1/teams/{team}
CreatecreateNone yet. Reserved for upcoming endpoints that change data.
UpdateupdateNone yet. Reserved for upcoming endpoints that change data.
DeletedeleteNone 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:

HeaderMeaning
X-RateLimit-LimitRequests allowed per minute (60).
X-RateLimit-RemainingRequests left in the current minute.
Retry-AfterOnly on 429 responses: seconds to wait before retrying.
X-RateLimit-ResetOnly 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.