Managing API Tokens

An API token (the API resource accesstoken, shown as API tokens in the UI) is a bearer credential that authenticates programmatic calls into Celigo -- the native integrator.io REST API, any custom APIs you have built in the account, and your MCP servers. It is the machine-to-machine equivalent of a user login: where a person signs in through the UI, a script presents an API token. Account API tokens are created by the owner or an administrator; personal access tokens are self-service for administrators, manage, and monitor users. Either kind is managed only in the integrator.io UI -- see Where Tokens Are Managed.

Two things to keep straight up front:

• Direction is inbound. An API token governs traffic coming into Celigo -- the opposite of connections and iClients, which authenticate Celigo's outbound calls out to external systems. This is the most common conceptual mix-up; see API Token vs Connection OAuth Token.
• The token value is a real secret. It is masked as ****** in API responses; only the UI's show-token action reveals it, and only to users who may manage the token (for a PAT, only its creator). Treat it like a password: never paste a real token into chat and never read one back.

Concerns when managing API tokens:

• Token kind -- a personal access token (PAT) tied to your own user vs an account API token owned by the account. See Personal Access Tokens (PATs) vs Account API Tokens.
• Access scope -- fullAccess (whole account) vs least-privilege resource scoping (_connectionIds, _exportIds, _importIds, _apiIds, _mcpServerIds). The two are mutually exclusive.
• Lifecycle -- generate, revoke, delete (a token must be revoked before it can be deleted).
• Expiry -- optional autoPurgeAt self-destruct for short-lived tokens.
• Secret handling -- move the value straight from the UI into the consumer's secret store; rotate rather than reuse a leaked token.
• Auto-managed variants -- connector integration tokens and APIM tokens you do not hand-craft.

API tokens are an account-administration concern, not a flow or integration resource.

What API Tokens Are For

Anything that needs to talk to Celigo without a human at a keyboard:

• CI/CD pipelines -- a deploy step that clones an integration, flips a setting, or runs a flow on release.
• Monitoring and alerting -- a script polling flow or error state and paging on failures, or pushing metrics to an observability stack.
• Calling your custom APIs and MCP servers -- external callers authenticate into APIs and MCP servers you have published using an API token (one of an MCP server's accepted auth modes).
• Ad-hoc API access -- hitting the integrator.io REST API from Postman, a notebook, or a one-off script.

When a user says "a token for our script", "authenticate our pipeline to Celigo", "call the Celigo API from our server", or "let our monitoring hit the API" -- that is an API token.

API Token vs Connection OAuth Token

"Access token" is overloaded -- the underlying resource is even named accesstoken -- so this is the mix-up to head off first. Same two words, opposite directions, different resources:

The test: who is proving identity to whom? An external caller proving it may use your account = API token (this skill). Celigo proving it may call their system = the connection's OAuth token.

It is also distinct from user permissions: a user record is a person's access to the account; an API token is a machine's. See managing-users.

Personal Access Tokens (PATs) vs Account API Tokens

Celigo has two kinds of inbound bearer token. Both live under the account's API tokens view, and both are sent the same way (Authorization: Bearer <token>) -- the integrator.io REST API and the Celigo CLI accept either:

Rule of thumb: a PAT authenticates you; an account API token authenticates a system. A PAT is the quick self-service option -- generate one for yourself and go -- but it is bound to your account membership (tokenType: "ashare"): it tracks your permission changes immediately, stops working if your membership is removed, and its 90-day default expiry will arrive mid-quarter. For automation that must outlive any one person -- CI/CD especially -- prefer a least-privilege account API token, or at minimum calendar the PAT rotation. The account owner can't create a PAT at all, so the owner's own scripts and CLI profile use an account API token.

Token Anatomy

The shape to remember: a named secret, plus an access scope that is either everything (fullAccess) or an explicit allow-list of resource ids.

Quick Reference

Access Scope Decision Matrix

Default toward least privilege: scope a token to exactly the resources its automation touches. A monitoring script that reads two flows' errors does not need account-wide access. Reserve fullAccess for automation that would be impractical to enumerate, and treat those tokens as the highest-value secrets to rotate and audit.

Minimum Fields

Generating a token requires at minimum:

• name -- a purpose-descriptive label (strongly recommended; it is the only identifier in the UI and audit logs)
• Exactly one access model: fullAccess: true or at least one scope array (_connectionIds, _exportIds, _importIds, _apiIds, _mcpServerIds). Setting both fails validation.

You never supply the token value -- it is generated by the platform and returned masked.

When You Need This Skill

• Creating, scoping, rotating, revoking, or deleting an API token
• A script, pipeline, monitor, or external client must authenticate into integrator.io
• Choosing between a personal access token and an account API token
• Deciding between account-wide and scoped programmatic access
• Untangling an "access token" question -- is it inbound (this skill) or a connection's outbound OAuth token (see configuring-connections)

Related Skills

• managing-users > Access Strategy Decision Matrix -- API tokens authenticate machines; user records authenticate people. Account API tokens and user records are both owner/administrator-controlled access.
• configuring-connections > iClients (OAuth Credential Stores) -- a connection's OAuth access token authenticates Celigo's outbound calls; do not confuse it with an inbound API token.
• building-apis > API Modes -- custom APIs have no authentication of their own; callers authenticate with an API token.
• building-mcp-servers > How to Build an MCP Server -- MCP servers accept an API token as one of their auth modes.

How to Manage API Tokens

1. Confirm this is an inbound-auth need

Before generating anything, confirm the requirement is a machine calling into Celigo. If instead something needs to authenticate out to an external system (Salesforce, NetSuite, an HTTP API), that is a connection's OAuth access token -- not an API token. Use configuring-connections. See API Token vs Connection OAuth Token.

Then decide the token kind. For your own CLI profile, scripts, or ad-hoc calls, the fastest path is a personal access token -- self-service in the UI, no scoping to design, 90-day default expiry (the account owner can't create one and uses an account API token instead). For shared or long-lived automation, continue below with an account API token. See Personal Access Tokens (PATs) vs Account API Tokens.

Every step below happens in the integrator.io UI, on the account's API tokens page -- there is no CLI or API path (see Where Tokens Are Managed). An agent's job is to work out the right settings and walk the user through them.

2. Audit existing tokens

On the API tokens page (the owner and administrators see every token; manage and monitor users see only their own PATs), review name/description (is the purpose clear?), fullAccess vs the scope arrays, revoked, autoPurgeAt, and whether it is an auto-managed apim or connector token. Revoke or purge stale tokens you no longer recognize.

3. Decide the scope

Use the Access Scope Decision Matrix. The honest question when someone asks for a token is "what will it actually call?" -- then scope to exactly that. Default to one or more scope arrays; reserve fullAccess for genuinely account-spanning automation.

Scope arrays hold real resource _ids. If you only have resource names, resolve them to ids first, then place the ids in the arrays:

celigo account search "<resource-name>"

If you cannot resolve the ids up front, generate the token and add scope in the UI rather than leaving it fullAccess by default.

4. Generate the token (one per consumer)

Default to one token per consumer -- per pipeline, per script, per external client. Independent tokens mean a leak or decommission affects exactly one consumer (you revoke that token and nothing else breaks) and the audit log attributes activity to the right caller. A single shared token turns every revocation into an outage for all of them.

Generate it on the API tokens page with a purpose name and the access model you chose: full access, or the specific connections, exports, imports, APIs, and MCP servers it may reach.

Move the secret straight to its consumer. Copy the generated value directly into the consuming system's secret store -- never into chat, a ticket, or a commit. Afterward the value stays masked (******) everywhere except the UI's show-token action. Generating is not idempotent: if a generate appears to fail, check the token list before trying again rather than minting a duplicate.

5. Set an expiry for temporary access

For a contractor engagement, a one-off migration, or a demo, set the token's auto-purge date (autoPurgeAt: within 30 days for account API tokens; PATs allow up to 90 and default to 90) so the token cleans itself up instead of lingering as a forgotten standing credential.

For ongoing automation a permanent token is fine -- pair it with a rotation habit: generate the replacement, cut the consumer over, then revoke the old one.

6. Revoke, then delete

Revoke and delete are sequential, not alternatives:

• Revoke the instant a token leaks or its consumer is retired. Authentication stops immediately while the record (and its audit trail) is preserved. Revoking sets revoked: true; an administrator can revoke another user's PAT.
• Delete only after the token is revoked -- revoke-before-delete is enforced. Deletion is a soft delete; the record is purged permanently 30 days later.

APIM tokens (apim: true) are the exception: they cannot be deleted at all -- revoking is the only lever.

Where Tokens Are Managed

Only in the integrator.io UI, on the account's API tokens page -- PATs and account API tokens both live there. The CLI has no token commands and the MCP server has no token tools, and the REST endpoints (/v1/accesstokens) reject every bearer-token caller -- API tokens and PATs alike -- with 403 not_allowed. A token can authenticate calls to other resources, but no script, CLI profile, or MCP session can list, generate, revoke, or delete tokens. When a user asks an agent to manage a token, the agent decides the settings and the user applies them in the UI.

The CLI still helps you prepare: resolve resource names into the ids a scoped token needs.

celigo account search "<resource-name>"

Pre-Submit Checklist

Before generating or updating an API token, verify:

• name/description states the token's purpose and consumer (it is the only identifier in audit logs)
• Exactly one access model is set -- fullAccess: true or scope arrays, never both (setting both fails validation)
• fullAccess is justified by genuinely account-wide automation; otherwise scope to specific resource ids
• Scope arrays contain real resource _ids (resolved from names), not placeholders
• For temporary access, autoPurgeAt is set and within 30 days
• The consumer gets its own token (not a shared one) so revocation stays isolated
• You are ready to capture the generated secret into a secret store -- not chat, tickets, or commits
• To delete: the token is already revoked: true and is not an apim token (which cannot be deleted)

Gotchas

1. API token = inbound; connection OAuth token = outbound. The single most common mix-up. If the thing authenticating is Celigo reaching out to another system, it is a connection's OAuth token, not an API token. See API Token vs Connection OAuth Token.
2. The token value is a secret -- never echo it. It is masked as ****** in API responses and revealed only through the UI's show-token action. Never accept a token value in chat and never read one back. If a user pastes a real token, treat it as compromised: revoke it and generate a new one rather than reuse it.
3. Only the UI reveals the value. The show-token action works for users who may manage the token -- and a PAT's value only for its creator, never for an administrator. If you can't reveal it, generate a replacement.
4. fullAccess and the scope arrays are mutually exclusive. Setting fullAccess: true alongside any of _connectionIds/_exportIds/_importIds/_apiIds/_mcpServerIds fails validation. Choose one model.
5. Revoke before delete -- always. A token must be revoked: true before it can be deleted; the platform enforces the order. Revoke is the instant safety action (authentication stops immediately, record preserved); delete is later cleanup (soft delete, purged after 30 days).
6. APIM tokens cannot be deleted. Tokens marked apim: true are managed by API management and have no delete path. Revoking is the only lever.
7. Auto-managed tokens are not hand-crafted. Connector integration tokens (carrying _integrationId/_connectorId) and APIM tokens (apim: true) are created by the platform -- do not try to author or duplicate them by hand.
8. autoPurgeAt must be within 30 days -- 90 for PATs. It is meant for short-lived tokens; a value further out is rejected. It self-deletes the record when it passes.
9. Creating is not idempotent. A generate that appears to fail may still have minted a live token. Check the API tokens list before retrying, or you may leave an orphaned credential.
10. Tokens can't manage tokens. /v1/accesstokens rejects every bearer-token caller with 403 not_allowed, and neither the CLI nor the MCP server has token commands. Don't script token creation or rotation -- it happens in the UI, signed in as a user.
11. A PAT belongs to its creator. Only the creator can edit, reveal, reset, or delete it; an administrator sees every PAT and can revoke one, but can't otherwise change it or reveal its value. Manage and monitor users see only their own PATs. A credential the team must manage jointly should be an account API token.
12. A PAT rides the owner's permissions -- and their 90-day clock. It inherits whatever the creating user can do (no scoping available), tracks permission changes immediately, stops working if the membership is removed, and expires after 90 days by default. Don't bury one in CI: use a scoped account API token there, or calendar the rotation.

Common Errors