Developer API Setup

This setup produces a server-side credential for Eigenn's public API. API keys are team-scoped and are shown only once when created.

Before You Start

• Select the team the integration should access.
• Use a workspace owner account to create or revoke team API keys.
• Confirm that the team's plan allows another API key.
• Decide whether the integration needs production or sandbox.
• List the exact resources and actions the integration requires.

1. Create a Restricted Key

1. Open Settings → Developer.
2. In API Keys, select Create API Key.
3. Enter a name that identifies the service and environment.
4. Choose an access preset:
   • All grants all public read and write scopes.
   • Read Only grants every readable public scope.
   • Restricted lets you select resource-specific read or write scopes.
5. Prefer Restricted and select only the needed scopes.
6. Select Create.
7. Copy the key immediately.

The full secret is visible only in the creation confirmation. If it is lost, create a replacement rather than trying to recover it.

2. Store the Key

Store the credential in a server-side secret manager. Do not put it in:

• browser code
• a mobile application bundle
• source control
• build logs
• analytics events
• screenshots or support tickets

Use a separate key for each service and environment so one credential can be rotated without disrupting unrelated integrations.

3. Choose the Base URL

The current public contract describes sandbox as staging-backed. Do not use it as evidence of production state.

4. Verify Authentication

A restricted key with users.read can call the current-user endpoint:

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

A successful response returns the authenticated user profile. It does not return the secret.

Interpret failures as follows:

• 401: the Authorization header or credential is missing, invalid, expired, or not bound to an accessible team
• 403: the credential is valid but lacks users.read
• 429: wait for the Retry-After interval before retrying

5. Inspect the Contract

Use the API Reference for interactive exploration or fetch the machine-readable document from:

https://api.eigenn.io/v1/openapi

Check each operation for:

• HTTP method and endpoint
• required scope
• required request fields
• status-specific response schemas
• pagination limits
• Idempotency-Key support

Do not infer an endpoint from a product page. Product capabilities such as workflow management can exist without a public API operation.

6. Prepare Writes

Before the first write:

1. test the same request in sandbox with representative data
2. choose a stable idempotency key for the logical write
3. keep the key at 128 characters or fewer
4. validate the response before starting dependent work
5. log the status, request ID when available, and idempotency status

Example customer creation:

curl --request POST \
  --url https://api.eigenn.io/v1/customers \
  --header "Authorization: Bearer $EIGENN_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: customer-acme-2026-07-11" \
  --data '{
    "name": "Acme Corporation",
    "email": "[email protected]"
  }'

The key needs customers.write. Creating a customer can upsert an existing matching record, so inspect the returned customer ID rather than assuming every successful request created a new row.

7. Rotate Safely

1. Create a replacement with the same or narrower scopes.
2. Deploy the replacement to the consuming service.
3. verify a read and one safe write if required
4. revoke the old key from Settings → Developer
5. monitor 401 responses and integration health

Revocation is team-wide and takes effect for future authenticated requests. Keep credentials separate enough that rotation has a clear owner.

Related Pages

• Authentication
• Errors
• Rate Limits
• SDKs
• Developer Platform