> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/api/getting-started/authentication.md).

# Authentication

This article covers authenticating a Celigo API using a bearer token. To authenticate a third-party connector, like NetSuite or Salesforce, use the **Connection** resource. Every request to a Celigo API requires a bearer token.

```http
Authorization: Bearer <YOUR_API_TOKEN>
```

## Token types

integrator.io issues two kinds of bearer token from **Resources → API tokens**: account-owned **service tokens** and user-owned **personal access tokens**. Both authenticate the same way, in the same header. These docs say "API token" for either kind when the type doesn't matter.

| Type                            | Who can create                               | Permissions                        | When to use                                                                             |
| ------------------------------- | -------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------- |
| **Service token — Full access** | Account owner, admin                         | Everything the account can do      | Trusted server-to-server automation owned by the team.                                  |
| **Service token — Custom**      | Account owner, admin                         | Only the resources you select      | Least-privilege access to specific connections, exports, imports, APIs, or MCP servers. |
| **Personal access token (PAT)** | Any user, including Manage and Monitor roles | Inherits your own user permissions | Individual access to the API, CLI, and Platform MCP without admin provisioning.         |

The **Auto purge token** field controls how long a token lives before it is automatically deleted. Service tokens offer never, 1 hour, 4 hours, 1 day, 4 days, 10 days, or 30 days, with no default. Personal access tokens add a **90 days** option and default to it.

## Create a service token

Service tokens are account-owned and admin-created. Use them for shared automation that should not be tied to one person's user.

1. Open **Resources → API tokens**, then select **+ Generate token**.
2. Choose **Service token**. Admins see the type menu; Manage and Monitor users can create only personal access tokens.
3. Name it something that tells you where it's used: `ci-deploy-bot`, `terraform-stack`. A description is optional.
4. Set **Auto purge token**. Short-lived is safer.
5. Choose the **Full access** or **Custom** scope under **Token permissions**.
6. Select only the specific resources the token can access, using the dropdown under each resource category — Connections, Exports, Imports, APIs, MCP servers. Applies to **Custom** tokens.
7. Select **Generate token**, then copy the token.

> ⚠️ **Copy the token from the create dialog and store it securely.** Owners and admins can reveal a service token later with **Reveal token**. Every plain-text reveal emails all owners and admins and is written to the audit log. A personal access token can be revealed only by its owner.

## Create a personal access token

A personal access token acts as you. It inherits your account permissions automatically, so there is no scope to configure and no way to escalate beyond what you can already do. If your permissions change, the token's access changes with them.

1. Open **Resources → API tokens**, then select **+ Generate token**.
2. Choose **Personal access token**. Manage and Monitor users skip this step — it is the only type available to them.
3. Name it after where it's used: `local-dev-tyler`, `claude-code`. A description is optional.
4. Set **Auto purge token**. PATs default to **90 days**, and shorter is safer. The panel shows the exact expiration timestamp.
5. Select **Generate token**, then copy the token and store it securely. Only you can reveal it again later with **Reveal token** — admins cannot.

You can create multiple personal access tokens. One per machine or tool is a reasonable pattern, so revoking one doesn't break the others.

**Lifecycle and oversight:**

* The token stops authenticating while your user is disabled. It is revoked permanently when your user is deleted.
* Admins see every PAT on the account in the token table (the **Scope** column shows `User`) and can revoke any of them.
* Admins cannot view or reset a token they did not create — **Reveal token** is available only to the owner.

## Rotating tokens

Tokens don't auto-rotate. Treat them like database passwords:

* Store them in your secrets manager, not in source code.
* Rotate on a schedule (quarterly is a reasonable default) and whenever a team member with access to the secret leaves.
* Create the new token **first**, roll it out to your deploys, and only then revoke the old one under **Action → Revoke token** — revoking invalidates immediately.

Personal access tokens encourage rotation by default: the 90-day auto-purge deletes the token on schedule, so create a replacement before the old one expires.

## Custom-scoped tokens

A Custom token restricts access to specific resource instances you select during creation. Under **Token permissions → Custom**, each resource category has a multi-select dropdown where you pick exactly which resources the token can reach:

| Category        | What you're selecting           |
| --------------- | ------------------------------- |
| **Connections** | Individual connection resources |
| **Exports**     | Individual export resources     |
| **Imports**     | Individual import resources     |
| **APIs**        | Individual API resources        |
| **MCP servers** | Individual MCP server resources |

If a resource isn't selected, the token cannot access it. Categories left empty grant no access to that resource type.

### What a connection-scoped token can do

Scoping a Custom token to a connection grants a narrow capability, not blanket access to everything that touches that connection. A connection-scoped token can:

* **Invoke ad-hoc exports and imports** against the selected connection — one-off reads and writes that run through it.

It **cannot**:

* Create, read, update, or delete the connection resource itself — or any other resource.
* Read flow errors or jobs.

For anything that involves flows, errors, jobs, or broader account activity, issue a token whose scope includes those resources (or a Full access token).

### Is there a read-only token?

Not as a scope setting. A service token is **Full access** or **Custom**, and Custom narrows access to specific resource *instances* — there is no read-only switch and no separate read / write / delete permission to set on the token itself.

You get read-only behavior from the **user** instead. A per-verb view / create / edit / delete model governs user access levels, and a [personal access token](#create-a-personal-access-token) inherits the permissions of whoever created it. So a PAT created by a Monitor-role user is effectively read-only, because that user cannot write through the UI either.

If you need a read-only credential, create the PAT from a user whose access level is already limited, rather than looking for a scope option on a service token.

## Tokens and the Platform MCP

The [Celigo Platform MCP](https://developer.celigo.com/mcp) authenticates two ways, and each one caps what an agent can reach:

* **OAuth sign-in** (the default for interactive clients) — the session acts as **you**, with your user permissions in the account and environment you pick at sign-in.
* **Bearer token** — the session runs with **exactly that token's permissions**, whether it's a service token or a PAT.

Either way the agent can do what you or the token could do through the REST API, and nothing more. There is no separate read-only MCP mode; to limit an agent, limit the credential you connect with.

Don't confuse this with the `mcp:read` / `mcp:write` scopes on the builder-side [`mcpServers` resource](https://developer.celigo.com/cli/commands/mcp-servers) — those govern MCP endpoints *you* publish to expose your own Tools and APIs, not the credential you use to reach the Platform MCP.

## Testing a token

{% tabs %}
{% tab title="cURL" %}

```bash
curl -s https://api.integrator.io/v1/tokenInfo \
  -H "Authorization: Bearer $CELIGO_API_TOKEN" \
  -w "\n--\nstatus=%{http_code}\n"
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const res = await fetch("https://api.integrator.io/v1/tokenInfo", {
  headers: { Authorization: `Bearer ${TOKEN}` }
});
console.log(`status=${res.status}`);
```

{% endtab %}

{% tab title="Python" %}

```python
res = requests.get(
    "https://api.integrator.io/v1/tokenInfo",
    headers={"Authorization": f"Bearer {TOKEN}"},
    timeout=10,
)
print(f"status={res.status_code}")
```

{% endtab %}

{% tab title="Celigo CLI" %}

```bash
celigo tokenInfo get
```

{% endtab %}
{% endtabs %}

| Status             | Meaning                                                                                            | What to do                                                                                                |
| ------------------ | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `200 OK`           | Token is valid. Works for service tokens and personal access tokens.                               | No action needed.                                                                                         |
| `401 Unauthorized` | Token is missing, malformed, expired, or revoked. For a PAT, the owning user may also be disabled. | Create a new token in **Resources → API tokens** and update your environment variable or secrets manager. |

See [Errors & status codes](/api/using-the-api/errors.md) for full details.

## Related

* [Environments & regions](/api/getting-started/environments.md) — tokens belong to one tenant in one region.
* [Errors & status codes](/api/using-the-api/errors.md) — what the API returns for every auth failure mode.
* [CLI: Authenticate](https://developer.celigo.com/cli/getting-started/authenticate) — how to wire the same token into the CLI.
* [Managing API tokens](https://docs.celigo.com/hc/en-us/articles/360019782431-Managing-API-tokens) — the Help Center reference for the tokens UI, including notification and audit behavior.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/api/getting-started/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.