Authentication overview

Okinawa API v3 uses OAuth 2.0 as its primary authentication mechanism, with support for API keys for simpler use cases. Every API request must include a valid access token or API key in the Authorization header. This guide covers both approaches in detail, along with best practices for credential management, scope control, and security hardening.

Getting your credentials

Navigate to Settings → API Credentials in your Okinawa dashboard. From there, you can create two types of credentials:

• OAuth Applications — For integrations that need to act on behalf of a user. You'll receive a client ID and client secret after registering your application.
• API Keys — For server-to-server communication where no user context is needed. API keys are scoped to your account and have configurable permissions.

When creating an OAuth application, you'll need to provide a redirect URI, a description, and the scopes your application requires. API keys can be created instantly with just a name and scope selection.

OAuth 2.0 flow

Okinawa supports the following OAuth 2.0 grant types, each designed for a specific use case:

• Authorization Code — The standard flow for server-side applications. The user is redirected to Okinawa to log in and authorize your application, then redirected back with an authorization code that you exchange for tokens. Supports PKCE for enhanced security.
• Authorization Code with PKCE — Recommended for single-page apps and mobile applications. The PKCE extension replaces the client secret with a dynamically generated code challenge, preventing authorization code interception attacks.
• Client Credentials — For machine-to-machine communication where no user context is needed. Your application authenticates directly using its client ID and secret to obtain an access token.
• Refresh Token — Used to obtain new access tokens without prompting the user again. Refresh tokens are returned alongside access tokens and can be used until they expire.

Implementing the Authorization Code flow

Here's a complete example of the Authorization Code flow:

# Step 1: Redirect user to authorization URL\nGET https://auth.okinawa.com/authorize\n ?response_type=code\n &client_id=your_client_id\n &redirect_uri=https://yourapp.com/callback\n &scope=workflows:read workflows:execute\n &state=random_csrf_token\n &code_challenge=base64url(sha256(verifier))\n &code_challenge_method=S256

# Step 2: Exchange authorization code for tokens\nPOST https://auth.okinawa.com/token\nContent-Type: application/x-www-form-urlencoded\n\ngrant_type=authorization_code\n&code=received_auth_code\n&redirect_uri=https://yourapp.com/callback\n&client_id=your_client_id\n&code_verifier=original_verifier

# Response:\n{\n "access_token": "eyJhbGciOiJSUzI1NiIs...",\n "refresh_token": "rt_abc123def456...",\n "token_type": "Bearer",\n "expires_in": 3600,\n "scope": "workflows:read workflows:execute"\n}

Token lifecycle

Understanding token lifecycles is critical for building reliable integrations:

• Access tokens expire after 1 hour (3,600 seconds). Always check the expires_in field in the token response and proactively refresh before expiration.
• Refresh tokens expire after 30 days of inactivity. Each use extends the expiration by another 30 days. If a refresh token expires, the user must re-authorize your application.
• ID tokens (if requested) contain user identity information in JWT format and are valid for 1 hour.

Best practice: implement automatic token refresh in your application. Check the expires_in value and refresh when 5 minutes remain. This prevents unnecessary 401 errors.

Scopes and permissions

Okinawa supports granular scopes for controlling API access. Scopes are requested during authorization and can be limited by organization administrators:

• workflows:read — Read workflow definitions and execution history
• workflows:write — Create, update, and delete workflow definitions
• workflows:execute — Trigger workflow runs manually
• integrations:read — View connected integrations and their status
• integrations:write — Connect, disconnect, and configure integrations
• agents:read — View agent configurations and execution logs
• agents:manage — Create, update, and delete agents
• secrets:read — Access secret names (never values)
• secrets:write — Create and update secrets
• admin:full — Full administrative access to all resources

API key authentication

For simpler use cases, API keys provide a straightforward alternative to OAuth:

curl -X GET https://api.okinawa.com/v3/workflows \\\n -H "Authorization: Bearer ok_api_abc123def456" \\\n -H "Content-Type: application/json"

API keys don't expire but can be revoked instantly from the dashboard. Each key has an associated set of scopes that determines what it can access. You can create multiple keys with different scopes for different parts of your infrastructure.

Security best practices

• Never expose tokens in client-side code — Keep access tokens and API keys on the server. Use the Authorization Code flow with PKCE for client-side applications.
• Use the minimum required scopes — Request only the permissions your integration needs. You can always request additional scopes later.
• Implement token rotation — Use refresh tokens to obtain new access tokens. Never store access tokens in long-lived sessions.
• Enable IP allowlisting — Restrict API key usage to specific IP addresses from your infrastructure.
• Monitor usage — Check the API usage dashboard regularly for unexpected patterns. Set up alerts for anomalous request volumes.
• Use webhook signatures — Verify the X-Okinawa-Signature header on incoming webhooks using your webhook secret to ensure requests are genuinely from Okinawa.