Authentication

The Elido API supports three credential types. Pick the one that matches the actor on whose behalf you’re making the call.

Personal Access Tokens (PAT)

Tokens scoped to a single user. Created from Settings → API Tokens in the dashboard. Best for ad-hoc scripts and personal automations.


Authorization: Bearer pat_a1b2c3d4...

PATs inherit the user’s workspace memberships and roles. They are revocable per token without affecting other tokens or the user’s session.

Workspace API Keys

Tokens scoped to a workspace, not a user. Created from Settings → Integrations → API Keys. Best for backend services and production integrations because they survive employee turnover.


Authorization: Bearer wsk_a1b2c3d4...

Workspace API keys are role-scoped - assign the minimum role necessary for the integration’s job. A key with the viewer role can read links and analytics but can’t create or modify them.

OAuth2 (third-party apps)

Apps installed from the integrations marketplace use OAuth2 authorization-code flow. Scopes are fine-grained:

Scope	Allows
`links:read`	List and read links
`links:write`	Create, update, archive links
`analytics:read`	Read click analytics
`webhooks:manage`	Subscribe and manage webhook endpoints
`members:manage`	Invite, remove, change roles
`billing:read`	Read invoices and subscription status

The OAuth flow follows RFC 6749 with PKCE. Endpoints are documented under Authorization in the API reference.

Rotation

PATs and Workspace API Keys are immutable: rotate by creating a new one and revoking the old.
OAuth tokens have a 1-hour access token + a 90-day refresh token. Refresh tokens rotate on every use (refresh-token rotation per RFC 6749 §10.4).

What goes wrong

Status	Why
`401 Unauthorized`	Header missing, token revoked, or expired
`403 Forbidden`	Token authentic but the actor lacks the role/scope
`429 Too Many Requests`	Rate limit - see Rate Limits

Errors come back in the standard envelope - see Errors.