Authentication
Authenticate Eigenn public API v1 requests with a scoped API key or 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 |
The current public contract describes sandbox as staging-backed. Keep credentials and test records separated by environment.
API Keys
Create keys from Settings → Developer → API Keys.
- Select Create API Key.
- enter a service and environment name
- choose All, Read Only, or Restricted
- prefer Restricted and select the needed resource scopes
- create and copy the secret
- store it 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 only once.
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 requires customers.read.
Scope Presets
| Preset | Meaning |
|---|---|
| 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. |
Operations document the exact scope they require. Common pairs include customers.read and customers.write, invoices.read and invoices.write, transactions.read and transactions.write, and reports.read and reports.write.
An API key with no granted scopes is rejected. A key also stops working 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 validates:
- 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 treat an OAuth application secret as an API key. Follow the selected OAuth grant and send the resulting access token as a bearer token.
401 and 403
| Status | Meaning |
|---|---|
| 401 | Authorization is missing, malformed, invalid, expired, or not bound to an accessible team. |
| 403 | Authentication succeeded, but the credential lacks a required scope. |
Scope errors can include the required and granted scopes. Log the response request ID when present before contacting support.
Credential Handling
- Never embed a privileged token in browser or mobile code.
- Do not put a token in a URL.
- Use one credential per service and environment.
- Rotate by deploying a replacement before revoking the old key.
- Remove unused OAuth redirect URLs.
- Revoke access when a vendor or team member no longer needs it.
- Avoid All access when a pair of read or write scopes is sufficient.
Verify 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 identifies the authenticated user. Confirm the user and environment before testing a write.