Authentication

Every request to the Nodion API must be authenticated with a Bearer token in the Authorization header. Nodion supports two kinds of API keys, each suited to a different use case.

Key types

User API Keys

User API Keys act on behalf of a specific user and can reach every project that user is a member of. They carry a set of scopes (fine-grained permissions), an optional project allow-list, and an expiry date. These are the right choice for CLIs, AI agents like Claude or Cursor, and personal automation scripts.

Create one in the Nodion dashboard under User Settings → Security → API Keys. The token is shown once right after creation, so store it safely right away.

Project API Keys

Project API Keys belong to a single project and have full access to that project regardless of who created them. They outlive the creating user and are intended for CI/CD pipelines, webhooks and other machine-to-machine automation.

Pick the project from Projects in the Nodion dashboard, open it and use the Security tab to create a new key.

Making a request

Send the token as an Authorization: Bearer <token> header. All endpoints live under https://api.nodion.com/v1/.

curl "https://api.nodion.com/v1/regions" \
  -H "Authorization: Bearer YOUR_API_KEY"

Selecting a project

User API Keys can access multiple projects. Tell Nodion which one you mean by sending an X-Nodion-Project header with the project's UUID. If you omit the header, Nodion falls back to the user's default project.

curl "https://api.nodion.com/v1/applications" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Nodion-Project: 5903725b-f554-4294-ab17-c992a765a001"

Project API Keys ignore this header, since they are already bound to exactly one project.

Scopes

User API Keys are gated by the scopes checked at creation time. A request that falls outside the token's scopes returns 403 Forbidden. Project API Keys are not scope-gated.

Scope	Allows
`read`	All `GET` requests (apps, deployments, envs, logs, metrics, projects).
`write`	Generic create / update / delete: domains, processes, SSH keys, DNS records.
`deploy`	`POST /applications/:id/deployments`, i.e. creating new deployments.
`env:read`	Read environment variable values.
`env:write`	Create, update or delete environment variables.
`logs:read`	Read application and deployment logs.

Scopes are additive. A token that should trigger deployments and read logs needs read, deploy and logs:read.

Project allow-list

When creating a User API Key you can restrict it to a subset of the projects you're a member of. A token with a project allow-list will return 403 for any request targeting a project outside the list, and GET /v1/projects will only list the allow-listed projects.

Leaving the allow-list empty grants the token access to every project the user currently has (or will have) access to.

Expiry and rotation

User API Keys can be created with a TTL of 30, 60 or 90 days, or without an expiry. Expired tokens return 401 Unauthorized. We recommend using the 90-day default and rotating tokens regularly, especially for keys pasted into AI tool configs.

Every key tracks its last_used_at timestamp so you can spot unused tokens in the dashboard and revoke them. Revocation is immediate: delete the key and any client using it loses access on the next request.

Error responses

Status	Meaning
`401 Unauthorized`	Missing, malformed or expired token.
`403 Forbidden`	Token is valid but lacks the required scope, role, or project access.
`429 Too Many Requests`	Rate limit hit. See Rate Limits.

Example response

A successful GET /v1/regions returns:

{
  "regions": [
    {
      "id": "5903725b-f554-4294-ab17-c992a765a001",
      "name": "EU Central",
      "slug": "euc"
    },
    {
      "id": "5e4ce16b-7409-4bb4-849a-9aec0ec0c7af",
      "name": "US East",
      "slug": "use"
    }
  ]
}

If you're integrating an AI agent, have a look at the AI page as well. The same tokens work against the hosted MCP server.