Authentication

Gonos supports two authentication methods: API keys for platform integrations and JWT tokens for portal users.

API keys

API keys are the primary authentication method for platform integrations. Include your key in the X-API-Key header on every request.

curl -X GET https://api.gonos.co/api/v1/candidates \
  -H "X-API-Key: td_live_your_key_here"

Key prefixes

Scopes

API keys can be scoped to specific permissions. If no scopes are set, the key has full access (legacy behavior).

Security best practices

• Never expose API keys in client-side code or version control
• Use scoped keys with minimum required permissions
• Rotate keys periodically via the dashboard
• Set expiration dates on keys when possible
• Use IP allowlists to restrict where keys can be used from

JWT tokens (portal users)

Admin and consumer portal users authenticate via email + password (or magic link) and receive JWT access + refresh tokens.

# Login
POST /api/v1/auth/login
{"email": "admin@example.com", "password": "your-password"}

# Response
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 900,
  "refresh_expires_in": 604800
}

# Use the access token
GET /api/v1/admin/overview
Authorization: Bearer eyJ...

Token lifecycle

Magic link authentication

Consumer portal users can sign in without a password via email magic links.

# Request a magic link
POST /api/v1/auth/magic-link/request
{"email": "consumer@example.com"}

# Consumer clicks the link in their email, then:
POST /api/v1/auth/magic-link/verify
{"token": "token-from-email-link"}

Enterprise SSO

Organizations can configure OIDC or SAML SSO providers to authenticate admin portal users via their corporate identity provider (Okta, Azure AD, Google Workspace, etc.).

See the SSO configuration page in your admin dashboard at /admin/settings/sso.

Rate limits

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After (on 429).