API Authentication
The REST API is available on every plan, including the free Starter plan. Requests to /api/v1 accept two kinds of credential:
| Credential | Prefix | Scope | How you get it |
|---|---|---|---|
| Account token | atl_ | Your whole account: all projects and forms | Device login from the CLI, MCP server, or an AI agent |
| Project API key | fep_ | Issued for one project. It can also manage the owner's other projects and forms. | Shown once when a project is created; rotate it in Project Settings → API Key |
Use an account token for tooling that acts on your behalf (the atlas CLI, the MCP server, AI coding agents). Use a project API key for server-side integrations such as Zapier or your own backend.
A few endpoints accept only a project API key: GET/DELETE /api/v1/submissions/{id}, the Files API, the video upload API (/api/v1/uploads), and PATCH /api/v1/projects/{id}. Deleting a project and updating a form (PATCH /api/v1/forms/{id}) require an account token.
Form endpoints (https://atlasforms.app/f/...) need no credential. They are public URLs and are safe to put in frontend code.
Using a Credential
Include the token or key in the Authorization header:
curl https://atlasforms.app/api/v1/projects \
-H "Authorization: Bearer atl_your_account_token"curl https://atlasforms.app/api/v1/submissions \
-H "Authorization: Bearer fep_your_api_key"Both formats are supported:
Authorization: Bearer (recommended)Authorization: Device Login (Account Tokens)
Device login lets a tool get an account token without you pasting a password or key anywhere. The tool starts a login, you approve it in your browser while signed in to Atlas, and the tool receives an atl_ token.
The easiest way is the CLI or MCP server, which run this flow for you. See Agent Setup. To run it yourself over HTTP:
1. Start a login
POST /api/v1/auth/devicecurl -s -X POST https://atlasforms.app/api/v1/auth/device \
-H "Content-Type: application/json" \
-d '{"client_name": "My Script"}'client_name is optional. It is shown to the user on the approval page.
{
"device_code": "<secret, keep it to yourself>",
"user_code": "BCDF-GHJK",
"verification_uri": "https://atlasforms.app/dashboard/connect",
"verification_uri_complete": "https://atlasforms.app/dashboard/connect?code=BCDF-GHJK",
"expires_in": 600,
"interval": 5
}Show the user verification_uri_complete and user_code. They open the link, check that the code matches, and click Approve. The request expires after expires_in seconds.
2. Poll for the token
POST /api/v1/auth/device/tokencurl -s -X POST https://atlasforms.app/api/v1/auth/device/token \
-H "Content-Type: application/json" \
-d '{"device_code": "<device_code>"}'Poll every interval seconds. Errors use the error field:
error | Meaning |
|---|---|
authorization_pending | The user has not approved yet. Keep polling. |
slow_down | You are polling too fast. Add 5 seconds to your interval. |
access_denied | The user denied the request. Stop polling. |
expired_token | The request expired. Start a new login. |
invalid_grant | Unknown or already used device code. Start a new login. |
On success:
{
"access_token": "atl_...",
"token_type": "bearer",
"user": { "email": "you@example.com" }
}Account tokens expire after one year. To share the token with the atlas CLI and the MCP server, save {"token": "atl_..."} to ~/.atlasrc with file mode 600, or set the ATLAS_TOKEN environment variable.
3. Revoke a token
DELETE /api/v1/auth/tokenRevokes the account token used to make the request. atlas logout calls this.
curl -s -X DELETE https://atlasforms.app/api/v1/auth/token \
-H "Authorization: Bearer atl_your_account_token"{ "revoked": true }This endpoint only accepts account tokens. Calling it with a project API key returns 400; rotate project keys in the dashboard instead.
You can also revoke any connected tool in Settings → API → Connected agents.
Security Best Practices
Keep Credentials Secret
atl_ tokens or fep_ keys in client-side code. Form endpoints don't need them.Rotate and Revoke
Rate Limits
API requests are rate limited per credential (per project API key or per account token):
| Endpoint type | Limit |
|---|---|
Most read endpoints (GET) | 100 requests/minute |
Most write endpoints (POST, PATCH, DELETE) | 50 requests/minute |
Rate limit headers are included in responses:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 2024-01-15T10:31:00ZWhen rate limited, you'll receive a 429 Too Many Requests response:
{
"error": "Rate limit exceeded"
}Error Responses
401 Unauthorized
The token or key is missing, invalid, expired, or revoked.
{
"error": "Invalid API key"
}403 Forbidden
The request is not allowed, for example because a plan limit is reached.
{
"error": "You've reached the maximum of 1 projects on the Starter plan"
}Example: Environment Variables
# .env
ATLAS_API_KEY=fep_your_api_key// Node.js
const response = await fetch('https://atlasforms.app/api/v1/submissions', {
headers: {
'Authorization': `Bearer ${process.env.ATLAS_API_KEY}`
}
});