API Authentication

The TIDALBAY API supports two authentication methods: API keys for server-to-server integrations and OAuth 2.0 for user-facing applications.

API Keys

API keys are the recommended authentication method for backend services and automated integrations. Each API key is scoped to a specific tenant and has configurable permissions.

Creating an API Key

Navigate to Settings → API Keys in the admin dashboard
Click Create API Key
Enter a descriptive name (e.g., "Production Integration")
Select the required scopes
Click Create and copy the key immediately

Security Note

API keys are shown only once upon creation. Store them securely in a secrets management system like HashiCorp Vault or AWS Secrets Manager. Never commit API keys to source control.

Using API Keys

Include your API key in the Authorization header:

curl -X GET "https://api.tidalbay.com/v1/employees" \
  -H "Authorization: Bearer tsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

API Key Scopes

Scope	Description
`employees:read`	Read employee data and scores
`employees:write`	Create and update employees
`scores:read`	Read security scores
`events:read`	Read security events
`events:write`	Submit custom events
`rules:read`	Read scoring rules
`rules:write`	Create and modify rules
`actions:read`	Read action history
`actions:execute`	Trigger manual actions

OAuth 2.0

Use OAuth 2.0 for user-facing applications that need to access TIDALBAY on behalf of users. We support the Authorization Code flow with PKCE.

OAuth Configuration

Configure your OAuth application in Settings → API → OAuth Apps. You'll need:

Client ID: Public identifier for your app
Client Secret: Keep this confidential (server-side only)
Redirect URIs: Allowed callback URLs

Authorization Flow

1. Redirect to Authorization

GET https://auth.tidalbay.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=employees:read+scores:read
  &state=RANDOM_STATE_VALUE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

2. Exchange Code for Token

POST https://auth.tidalbay.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=https://yourapp.com/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code_verifier=CODE_VERIFIER

3. Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "dGVzc2VyYV9yZWZyZXNoXzEyMzQ1Njc4OTA...",
  "scope": "employees:read scores:read"
}

Token Expiration

Access tokens expire after 15 minutes. Use the refresh token to obtain new access tokens without requiring user re-authentication.

Refreshing Tokens

POST https://auth.tidalbay.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Rate Limits

API requests are rate-limited to ensure fair usage:

Plan	Requests/Minute	Burst Limit
Starter	60	100
Professional	300	500
Enterprise	1000+	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1640000000

Error Responses

Authentication errors return appropriate HTTP status codes:

Status	Code	Description
401	`UNAUTHORIZED`	Missing or invalid credentials
403	`FORBIDDEN`	Valid credentials but insufficient scope
429	`RATE_LIMITED`	Too many requests