Authentication

API Key Authentication

Every API request must include a valid API key in the Authorization header. API keys are scoped to an organization and carry the permissions of the key creator.

curl https://api.interna.dev/v1/users \
  -H "Authorization: Bearer sk_live_your_api_key"

Bearer Tokens

For user-facing applications, exchange credentials for short-lived bearer tokens using the token endpoint.

const { token, expiresAt } = await interna.auth.createToken({
  userId: "usr_abc123",
  scopes: ["read:users", "write:users"],
  expiresIn: "1h",
});

Session Management

Tokens expire after their configured TTL. Use refresh tokens for long-lived sessions without requiring users to re-authenticate.

Security Best Practices

• Never expose API keys in client-side code or public repositories.
• Use environment variables for all secrets.
• Rotate API keys regularly and revoke compromised keys immediately.
• Apply the principle of least privilege when creating scoped tokens.
• Enable webhook signature verification to prevent spoofed events.