API quickstart
Prepare a credential and make your first request to the FortyOne API.
Before you begin
You need a FortyOne account, access to the target workspace, and a personal access token with only the scopes required by your integration. FortyOne shows the token once, so copy it directly into a secret manager.
Create a token. Open Settings → API → Access tokens, choose an expiry, and select the smallest useful set of scopes.
Choose an operation. Open the API reference and select the resource you want to read or change.
Authorize the request. Send one Authorization: Bearer <token> header.
Keep the token out of URLs, browser storage, source code, and logs.
Handle the response. Read the typed data object on success. On failure,
branch on error.code and retain X-Request-ID for troubleshooting.
Request checklist
| Concern | What to do |
|---|---|
| Base URL | Use https://api.fortyone.app/api/v1. |
| Authentication | Send one bearer header over HTTPS. |
| Writes | Supply Content-Type: application/json and an Idempotency-Key when the operation requires it. |
| Pagination | Treat cursors as opaque and follow meta.nextCursor. |
| Rate limits | Respect RateLimit, RateLimit-Policy, and Retry-After. |
| Troubleshooting | Record X-Request-ID, not the bearer token or sensitive body fields. |
What to read next
- Authentication explains token storage, rotation, and revocation.
- Scopes and access explains least privilege.
- Idempotent writes explains safe retries.
- API reference contains the exact request and response examples for every published operation.