Authentication

Protected Eigenn API operations accept one credential format:

Authorization: Bearer <token>

The token can be an Eigenn API key or an OAuth access token. The public contract does not document X-API-Key, query-string credentials, cookies, or basic authentication for protected resource operations.

Base URLs

In the current public contract, the sandbox environment runs on the api-staging host. Keep the credentials and the test records separate for each environment.

API Keys

Create keys from Settings → Developer → API Keys.

1. Select Create API Key.
2. Enter a name for the service and the environment.
3. Select All, Read Only, or Restricted. We recommend Restricted.
4. Select the necessary resource scopes.
5. Create the key.
6. Copy the secret.
7. Store the secret in a server-side secret manager.

Only a workspace owner can create, rotate, or revoke a team API key. Plan limits apply. The full secret appears one time only.

Example:

curl --request GET \
  --url https://api.eigenn.io/v1/customers?pageSize=25 \
  --header "Authorization: Bearer $EIGENN_API_TOKEN" \
  --header "Accept: application/json"

This request needs customers.read.

Scope Presets

Each operation documents the exact scope that it needs. Common pairs include customers.read and customers.write, invoices.read and invoices.write, transactions.read and transactions.write, and reports.read and reports.write.

Eigenn rejects an API key that has no granted scopes. A key also becomes invalid when its user no longer has access to the bound team.

OAuth

The public authorization server supports:

• authorization code
• refresh token
• client credentials

Create and manage OAuth applications in Settings → Developer → OAuth Applications.

The authorization flow confirms:

• client ID
• exact registered redirect URL
• requested scopes
• selected team membership
• S256 PKCE for public clients

Authorization and token endpoints:

• https://api.eigenn.io/v1/oauth/authorize
• https://api.eigenn.io/v1/oauth/token

OAuth-capable clients can use the discovery documents at:

• https://api.eigenn.io/.well-known/oauth-protected-resource
• https://api.eigenn.io/.well-known/oauth-authorization-server

Do not use an OAuth application secret in place of an API key. Follow the OAuth grant that you selected. Then send the access token that you get in the Authorization: Bearer header.

401 and 403

Scope errors can include the necessary scopes and the granted scopes. If the response includes a request ID, log it before you contact support.

Handle Credentials

• Never embed a privileged token in browser or mobile code.
• Do not put a token in a URL.
• Use one credential for each service and each environment.
• To rotate a key, deploy the replacement key before you revoke the old key.
• Delete unused OAuth redirect URLs.
• Revoke access when a vendor or team member no longer needs it.
• Do not use All access when a pair of read and write scopes is enough.

Confirm a New Credential

With users.read, call:

curl --request GET \
  --url https://api.eigenn.io/v1/users/me \
  --header "Authorization: Bearer $EIGENN_API_TOKEN"

A successful response shows the authenticated user. Confirm the user and the environment before you test a write.

Related Pages

• Developer API Setup
• Errors
• Rate Limits
• Developer Platform