Name: managing-api-tokens
Author: celigo

Manage Celigo API tokens (the accesstoken resource) -- bearer credentials that authenticate inbound programmatic calls into integrator.io's REST API, custom APIs, and MCP servers. Covers personal access tokens (PATs) versus account-level API tokens, least-privilege scoping versus full access, the re

<! TIER:1 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]( 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]( 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]( personal access tokens pats vs account api tokens). Access scope fullAccess (whole account) vs least privilege resource scoping ( connectionIds , exportIds , importIds , apiIds , mcpServerIds , topicIds , fileStoragePaths ). The two are mutually exclusive. Where it may connect from an account API token can be limited to known IP ranges by assigning it a network policy ( networkPolicyId ). Lifecycle generate, revoke (and reactivate), 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: integrator.io API token Connection OAuth access token Direction Inbound authenticates calls into Celigo Outbound authenticates Celigo's calls out to an external system Proves identity An external caller → Celigo Celigo → the external system Lives on The account ( accesstoken resource this skill) A specific connection (produced by its OAuth flow, optionally via an iClient) Managed with This skill [configuring connections](../configuring connections/SKILL.md) 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](../managing users/SKILL.md). Personal Access Tokens (PATs) vs Account API Tokens Celigo has two kinds of inbound bearer token: the personal access token, and the account API token, which the platform calls a service token ( GET /v1/tokenInfo reports one as token.type: "service" ). 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: Personal access token (PAT) Account API token Who can create one Administrators, manage, and monitor users, each for themselves not the account owner, and never on another user's behalf Owner/administrator only Whose access it grants Yours it inherits your own effective permissions The account's fullAccess or an explicit resource id allow list Scoping None to configure it always mirrors what you can do fullAccess vs scope arrays (this skill's main concern) Expiry Defaults to 90 days ; autoPurgeAt up to 90 days out Optional autoPurgeAt up to 30 days out; otherwise long lived Managed by Its creator. An administrator can also revoke it, but can't change it or reveal its value; manage and monitor users see only their own PATs Any owner/administrator Best for Your own scripts and ad hoc API calls Shared automation: CI/CD, monitoring, external callers of APIs and MCP servers 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, is blocked while your user is disabled and revoked when your user is deleted, 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 scripts use an account API token. A person's own work in the CLI needs no token: celigo login (CLI 2026.10.1 and later) signs in through the browser with OAuth and, like a PAT, carries the signed in person's own permissions the owner's included with no token to generate, hand over, or rotate. Tokens are for what runs without a person. Token Anatomy Field Type Purpose name / description string What the token is for the only thing identifying it in the UI and audit logs. Use a purpose name ( CI/CD Pipeline , Prod Monitoring ). token string (secret) The bearer value. Masked as in API responses; the UI's show token action reveals it to users who may manage the token. fullAccess boolean Token can reach any resource in the account. Mutually exclusive with the scope arrays. connectionIds , exportIds , importIds , apiIds , mcpServerIds , topicIds array of ids Least privilege scope the token reaches only the listed resources (for topicIds , it publishes to and reads only those Event Streams topics). Mutually exclusive with fullAccess . fileStoragePaths array of paths Celigo Storage folders the token may reach, each with everything beneath it: at most 7, each starting and ending with / . Mutually exclusive with fullAccess . networkPolicyId id The network policy whose IP allow and deny lists gate every request made with this token. Account API tokens only: a PAT follows the workspace user sign in policy instead. Assigned on the token in the UI. revoked boolean true disables the token (authentication stops immediately). Must be true before the token can be deleted. A revoked token can be reactivated ( revoked back to false ) until it's deleted. autoPurgeAt timestamp Optional self destruct time (within 30 days for account API tokens; up to 90 days for PATs). The record is removed automatically once it passes. lastUsedAt timestamp When the token last authenticated a request the Last used column. Absent until first use, recorded in batches (it can trail the latest call by a few minutes), and never changes lastModified . Account API tokens only: a PAT's record doesn't show it. apim boolean Marks an APIM managed token. APIM tokens cannot be deleted. integrationId / connectorId id Present on auto managed connector integration tokens (set by the platform, not hand crafted). tokenType / aShareId string / id Present on PATs: tokenType: "ashare" binds the token to the creating user's account membership. Absent on account API tokens. 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 The token will... Scope Set Serve one automation touching specific resources Least privilege (default) One or more of connectionIds , exportIds , importIds , apiIds , mcpServerIds , topicIds , fileStoragePaths ; omit fullAccess Call one custom API or one MCP server Least privilege apiIds or mcpServerIds scoped to that resource Be used only from known addresses (a partner's or a pipeline's IP ranges) Any scope, plus a network policy A network policy listing those ranges, assigned to the token ( networkPolicyId ). A custom API has no IP setting of its own, so the restriction goes on the token its callers use Run genuinely account wide automation (backup/export tool, admin provisioning) Full access (the exception) fullAccess: true ; omit all scope arrays Manage the Celigo hosted SFTP file server or its partner accounts Full access (required) fullAccess: true on an account API token every file server route refuses a scoped token, and every PAT, with 403 FILESERVER FULL ACCESS TOKEN REQUIRED ([managing file storage](../managing file storage/references/file server.md)) 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 , topicIds , fileStoragePaths ). 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](../configuring connections/SKILL.md)) Related Skills [managing users Access Strategy Decision Matrix](../managing users/SKILL.md access strategy decision matrix) API tokens authenticate machines ; user records authenticate people . Account API tokens and user records are both owner/administrator controlled access. [config