How to Create a Span API Token

Last updated: October 27, 2026

Span supports two kinds of API token: a Personal Access Token that acts as you, and a service account token for shared tools and automation.

Why it matters

  • For developers: a token lets scripts, dashboards, agents, and the Span MCP server read your Span data.

  • For admins: service accounts keep automation credentials separate from any one person, so a job doesn't break when someone leaves.

How it works

  • Personal Access Token: tied to your account. It sees exactly what you can see in Span, no more. Best for personal scripts or quick one-off integrations. Each person has one token at a time.

  • Service account token: a service account is a non-human user for integrations, automation, and shared tooling. It sees nothing until someone adds it to a permission group, and then it sees what those groups allow.

  • Both authenticate as a bearer token in the Authorization header.

How to create a token

Option 1: Personal Access Token

  1. Go to Settings → Access Token (under Personal).

  2. Click Generate.

  3. Copy the token and store it securely. You won't be able to view it again.

Once you have a token, the same page shows when it was generated and when it was last used ("Never used" until the first call). Use the menu there to Regenerate it, which revokes the old token, or Revoke it.

Option 2: Service account token (recommended for automation)

You need the Manage Service Accounts permission. Owners and Admins have it by default.

  1. Go to Settings → Service Accounts (under Organization).

  2. Click Create Service Account. Give it a descriptive name (for example, ci-bot or metrics-ingest), an email tag, and an optional description. Span builds the service account's email from your own address plus the tag, for example you+ci@company.com.

  3. Optionally, use Allowed Roles and Allowed People to choose who else in your organization can see and manage this service account. You always keep access to the ones you create or edit.

  4. In the service account's row menu, click Manage Token, then Generate.

  5. Copy the token and store it securely. It won't be shown again.

Give the service account access to data. Add it to a permission group in Settings → Permission Groups. The Permission Groups column on the Service Accounts page shows which groups it belongs to.

Using your token

Include the token as a bearer token in the Authorization header of your API requests:

Authorization: Bearer <your-token>

API reference: api.span.app/docs-next for the Knowledge Graph API, and api.span.app/docs for the v1 API, including the Span Sync API.

Things to know

  • A token is only as wide as its permissions. Worked example: your personal token can read Pull Requests data for the 14 people in your reporting line because your permission group covers them. A service account in a group scoped to two teams reads only those two teams' data, even though it uses the same API.

  • Some endpoints need a specific permission. Posting roster data to the Span Sync API needs a token whose owner (or service account group) holds Manage Directory Sync.

  • Prefer service accounts over personal tokens for shared tools and automation.

  • Use descriptive names for service accounts so their purpose is clear.

  • Rotate tokens regularly and revoke any you no longer need. Token creation and revocation appear in the audit log.

  • Grant the minimum permissions each service account needs.

Related articles

Need help?

Contact your Span account team or reach out to support@span.app.