Authentication
Authenticate Eigenn public API v1 requests with a scoped API key or an OAuth access token.
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
| Environment | Base URL |
|---|---|
| Production | https://api.eigenn.io/v1 |
| Sandbox | https://api-staging.eigenn.io/v1 |
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.
- Select Create API Key.
- Enter a name for the service and the environment.
- Select All, Read Only, or Restricted. We recommend Restricted.
- Select the necessary resource scopes.
- Create the key.
- Copy the secret.
- 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
| Preset | Description |
|---|---|
| apis.all | Expands to every public resource read and write scope. |
| apis.read | Expands to every public resource read scope. |
| Restricted | Stores only the selected resource scopes. |
Each operation documents the exact scope that it needs. The public contract uses these scopes:
| Resource | Read scope | Write scope |
|---|---|---|
| Bank accounts | bank-accounts.read | bank-accounts.write |
| Chat | — | chat.write |
| Customers | customers.read | customers.write |
| Documents | documents.read | documents.write |
| Inbox | inbox.read | inbox.write |
| Invoices | invoices.read | invoices.write |
| Metrics | metrics.read | metrics.write |
| Notifications | notifications.read | notifications.write |
| Reports | reports.read | — |
| Search | search.read | — |
| Tags | tags.read | tags.write |
| Teams | teams.read | teams.write |
| Tracker entries | tracker-entries.read | tracker-entries.write |
| Tracker projects | tracker-projects.read | tracker-projects.write |
| Transactions | transactions.read | transactions.write |
| Users | users.read | users.write |
| Workflows | workflows.read | workflows.write |
Reports and search are read-only. Chat has no read scope.
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:
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
| Status | Description |
|---|---|
| 401 | The Authorization header is absent, malformed, invalid, expired, or not bound to an accessible team. |
| 403 | Authentication succeeded, but the credential lacks a necessary scope. |
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.