A
Atlas
...

API Authentication

The REST API is available on every plan, including the free Starter plan. Requests to /api/v1 accept two kinds of credential:

CredentialPrefixScopeHow you get it
Account tokenatl_Your whole account: all projects and formsDevice login from the CLI, MCP server, or an AI agent
Project API keyfep_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:

bash
curl https://atlasforms.app/api/v1/projects \
  -H "Authorization: Bearer atl_your_account_token"
bash
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

    http
    POST /api/v1/auth/device
    bash
    curl -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.

    json
    {
      "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

    http
    POST /api/v1/auth/device/token
    bash
    curl -s -X POST https://atlasforms.app/api/v1/auth/device/token \
      -H "Content-Type: application/json" \
      -d &#x27;{"device_code": "<device_code>"}'

    Poll every interval seconds. Errors use the error field:

    errorMeaning
    authorization_pendingThe user has not approved yet. Keep polling.
    slow_downYou are polling too fast. Add 5 seconds to your interval.
    access_deniedThe user denied the request. Stop polling.
    expired_tokenThe request expired. Start a new login.
    invalid_grantUnknown or already used device code. Start a new login.

    On success:

    json
    {
      "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

    http
    DELETE /api/v1/auth/token

    Revokes the account token used to make the request. atlas logout calls this.

    bash
    curl -s -X DELETE https://atlasforms.app/api/v1/auth/token \
      -H "Authorization: Bearer atl_your_account_token"
    json
    { "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

  • Never commit tokens or API keys to version control
  • Use environment variables in production
  • Don't expose atl_ tokens or fep_ keys in client-side code. Form endpoints don't need them.
  • Never paste a token into an AI chat. Use device login instead.
  • Rotate and Revoke

  • Rotate project API keys in Project Settings → API Key if one may have leaked
  • Revoke account tokens you no longer use in Settings → API → Connected agents
  • Rate Limits

    API requests are rate limited per credential (per project API key or per account token):

    Endpoint typeLimit
    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:00Z

    When rate limited, you'll receive a 429 Too Many Requests response:

    json
    {
      "error": "Rate limit exceeded"
    }

    Error Responses

    401 Unauthorized

    The token or key is missing, invalid, expired, or revoked.

    json
    {
      "error": "Invalid API key"
    }

    403 Forbidden

    The request is not allowed, for example because a plan limit is reached.

    json
    {
      "error": "You've reached the maximum of 1 projects on the Starter plan"
    }

    Example: Environment Variables

    bash
    # .env
    ATLAS_API_KEY=fep_your_api_key
    javascript
    // Node.js
    const response = await fetch('https://atlasforms.app/api/v1/submissions', {
      headers: {
        'Authorization': `Bearer ${process.env.ATLAS_API_KEY}`
      }
    });