Authentication and API Clients

Eos organization administrators create private API Clients in Eos Settings. Each client is a licensed, non-human Eos principal with fixed organization membership, explicit Eos Roles, and confidential OAuth credentials.

Availability and licensing

• Business and Enterprise organizations include one Manager-level API Client per organization.
• The included Manager client can receive Member, Manager, Finance, and HR Roles.
• Each additional client consumes a purchased Regular or Manager license.
• Regular API Clients can receive the Member Role.
• Manager API Clients can receive Member, Manager, Finance, and HR Roles.
• API Clients cannot receive Admin, Owner, provider, or internal Roles.
• Trial and Team plans do not support API Clients in v1.

API Clients cannot log into the Eos user interface. They do not have passwords, MFA recovery, personal email identities, or personal provider connections.

Administrator setup

Named organization administrators manage clients at Settings → API Clients.

Creation requires:

1. A unique client name and optional description.
2. A Regular or Manager license selection.
3. One or more Roles allowed by that license.
4. Confirmation of the included or paid license assignment.

The first eligible Business/Enterprise client automatically uses the included Manager entitlement. Additional clients use an available purchased license or enter the existing purchase flow.

On creation, Eos displays the client secret exactly once. Eos stores only a strong hash.

Obtain an access token

POST /oauth/token

This endpoint is outside /v1 because it implements the OAuth protocol.

curl https://api.eoshq.com/oauth/token \
  -u 'apic_01J8Q4W9N0TS9AF1CXY6J5KX2F:CLIENT_SECRET' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&scope=eos.api'

Successful response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "eos.api"
}

Clients request another access token when the current token expires. The Client Credentials flow does not issue refresh tokens.

Token errors

Token failures follow the OAuth error response format. Resource-server failures use Eos problem details.

Call the API

curl https://api.eoshq.com/v1/me \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Accept: application/json'

Get the current principal

GET /v1/me

Operation ID: getCurrentPrincipal.

Required Role: any active API Client Role.

{
  "object": "api_client_principal",
  "id": "apic_01J8Q4W9N0TS9AF1CXY6J5KX2F",
  "name": "Salesforce project synchronizer",
  "organization_id": "org_01J8Q4VYG8QF9MR6X2F3XVBJPQ",
  "license": {
    "level": "manager",
    "source": "included",
    "status": "active"
  },
  "eos_roles": ["manager"],
  "record_access": "organization_wide_by_role",
  "scope": "eos.api"
}

The response reflects current Roles and license state, not a stale snapshot from token issuance.

Runtime authorization

Every request performs these checks:

1. Validate token signature, issuer, audience, expiry, and client ID.
2. Load the current API Client and organization state.
3. Require an active license and subscription.
4. Load current Eos Roles and authorization version.
5. Enforce API Client principal-type exclusions.
6. Enforce the operation's Role, metadata, and workflow rules.

Roles are not accepted from request data. An API Client cannot select another organization or actor.

Organization-wide-by-Role access

API Clients bypass project membership and assignment-based row filtering. They do not bypass:

• Object and field policy.
• Eos Role or Skill Role fences.
• Module entitlements.
• Workflow state.
• Soft deletion and retention rules.
• Named-user requirements for formal approvals and personal connections.
• Control-plane prohibitions.

Member subjects

Where a page documents a subject, the caller may identify a member:

{
  "subject": {
    "member_id": "alice@example.com"
  }
}

The member_id value is the member's normalized email address and must match a member inside the API Client's organization. There is no separate API-specific member identifier. The API Client remains the actor, and only its Roles authorize the operation. Supplying a subject never exposes the subject's personal OAuth connections or permits approval as that person.

Credential rotation

Named administrators can create a replacement secret. At most two secrets may be active during a short rotation window.

• The new secret is displayed once.
• Existing access tokens remain short-lived.
• The administrator may revoke the old secret immediately.
• Disabling the client invalidates all credentials and denies resource requests.
• Rotating credentials does not consume another license.

Disable, release, and delete

Plan downgrade or subscription suspension never deletes a client. It marks affected clients license-inactive and rejects token issuance and API requests until entitlement is restored.

Control-plane restrictions

API Clients cannot use v1 to manage clients, licenses, subscriptions, billing, organization ownership, Roles, security policy, or provider administration. Those actions require a named administrator through Eos Settings.

Security requirements for client applications

• Use API Clients only from confidential server environments.
• Never embed a client secret in browser, mobile, desktop, or distributed source code.
• Store the secret in a managed secret store.
• Rotate it when staff or infrastructure access changes.
• Do not log access tokens or secrets.
• Use a distinct API Client for each integration and security boundary.
• Assign the minimum license and Roles needed.
• Include a unique X-Client-Request-Id in calls.

Next: Organization API.