Skip to content
Onplana Docs

Create API tokens

All plans Any member

Personal access tokens (PATs) authenticate API requests without a browser session, for scripts, integrations, CI jobs, and AI agent connections. A token acts as you, in one organization, limited to the scopes you grant it.

Create a token

Section titled “Create a token”

  1. Open Settings and go to the Developer tab.

  2. Start a new token and give it a descriptive name (“Reporting script”, “Build pipeline”), so future-you knows what it is for.

  3. Pick the organization the token belongs to. A token is bound to one organization and carries the role you hold there.

  4. Select scopes. Grant the least the integration needs: read-only project and task scopes for a reporting script, write scopes only for tools that change data.

  5. Optionally restrict the token to specific projects. A project-scoped token cannot read or touch anything outside the projects you select, even if your own access is broader.

  6. Optionally set an expiry date, then create the token.

The token value is shown once. Copy it immediately; afterward only a short prefix is displayed for identification.

Revoke a token

Section titled “Revoke a token”

Revoke any token from the same Developer tab. Revocation is immediate: the next request with that token is rejected. Each token also shows when it was last used, which makes it easy to spot dead ones worth cleaning up.

Agent connections use the same tokens

Section titled “Agent connections use the same tokens”

When you connect an external AI agent (Claude, Cursor, and other MCP clients), Onplana mints the same kind of token under the hood, with an agent purpose, a 90-day default expiry, and its own management surface under Settings → Agents. Project scoping works there too, so you can hand an agent exactly one project. See Connect an external agent.

Good to know

Section titled “Good to know”
  • A token can never do more than you can. Scopes narrow your access, they never widen it.
  • Tokens cannot create other tokens, and security surfaces (sessions, 2FA, token management itself) always require a real sign-in.
  • Token creation requires a verified email address.

Best practices

Section titled “Best practices”
  1. Always set an expiry. Long-lived tokens are an audit liability. 90 days = reasonable default; rotate annually for permanent integrations.
  2. Grant minimum scopes. Reporting script = read-only. Webhook receiver = write to one project. Never grant broad scopes for narrow tasks.
  3. Project-scope when possible. Even for write tokens, scope to the specific projects the integration needs. Limits blast radius if leaked.
  4. Store tokens in secret manager. Never check into source control. Use 1Password / Vault / GitHub Secrets.
  5. Name tokens for the consumer. “Reporting script (Bob)” beats “Token 1”. Audits + reviews become much easier.

Troubleshooting / common pitfalls

Section titled “Troubleshooting / common pitfalls”
  • Token rejected with 401. Three causes: (a) revoked; (b) expired; (c) scope insufficient.
  • Token created but not displayed. Shown ONCE at creation. Regenerate if lost.
  • 401 after expiry. Tokens silently expire. Set up reminder before expiry.
  • Project-scoped token denied for cross-project read. By design. Create separate token for separate scope.
  • Agent token revoked by admin. Admins can revoke agent connections. Reconnect with admin consent.

How this combines with other features

Section titled “How this combines with other features”

Coming from another tool

Section titled “Coming from another tool”
ToolMapping
GitHub personal access tokensDirect concept
GitLab project access tokensDirect
Atlassian API tokensDirect
ServiceNow OAuthDirect
Custom API keysStandard pattern

FAQs

Section titled “FAQs”

A token leaked. What do I do? Revoke it immediately from Settings → Developer, then review what it touched: the token row shows last use, and on Enterprise plans the audit log records its activity.

Do tokens stop working when I sign out or change my password? No. Tokens are independent of browser sessions; only revocation or expiry ends them. See Manage sessions and devices for the session side.

Can an admin revoke my tokens? Your general tokens are yours alone. Agent connections are the exception: organization admins can revoke a member’s agent connection from the oversight view, since agents act inside shared projects.

Are token rates limited? Yes, same as session API. Token requests share the per-user rate limit.

Can I rotate a token without disruption? Create new token with same scopes; update consumer; revoke old one. The window of dual-validity = your rotation time.

Do tokens carry IP allowlist + 2FA enforcement? IP allowlist: yes. 2FA: bypassed by token (tokens are their own auth).

Section titled “Related”