Authentication

Learn how to authenticate with the Futurity API using OAuth 2.0 or API keys.

Authentication Methods

Method	Use Case
OAuth 2.0	User-authorized applications
API Keys	Server-to-server integrations

OAuth 2.0

Overview

OAuth 2.0 allows your application to act on behalf of a user. Use this for:

• Applications where users log in
• Integrations that need user consent
• Web and mobile applications

Authorization Code Flow

1. Redirect user to authorization

   GET https://futurity.work/oauth/authorize
     ?client_id=YOUR_CLIENT_ID
     &redirect_uri=YOUR_REDIRECT_URI
     &response_type=code
     &scope=read write
     &state=RANDOM_STATE

2. User grants permission

   User sees a consent screen and approves your app.

3. Receive authorization code

   User is redirected to your redirect_uri:

   https://your-app.com/callback?code=AUTH_CODE&state=RANDOM_STATE

4. Exchange code for tokens

   POST https://futurity.work/oauth/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code
   &code=AUTH_CODE
   &redirect_uri=YOUR_REDIRECT_URI
   &client_id=YOUR_CLIENT_ID
   &client_secret=YOUR_CLIENT_SECRET

5. Receive tokens

   {
     "access_token": "eyJ...",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "eyJ...",
     "scope": "read write"
   }

Refreshing Tokens

When access tokens expire, use the refresh token:

POST https://futurity.work/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

Response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJ..."
}

Note

Refresh tokens may be rotated. Always store the new refresh token from the response.

Scopes

Request only the scopes you need:

Scope	Access
read	Read-only access to resources
write	Create and modify resources
corint	Access Corint conversations
vault	Access Vault files
workflows	Access workflows
organization	Organization management

Combine scopes with spaces:

scope=read write vault

Token Lifetimes

Token	Lifetime
Access token	1 hour
Refresh token	30 days

API Keys

Overview

API keys are for server-to-server communication where no user interaction is needed. Use for:

• Backend services
• Scheduled jobs
• System integrations

Creating API Keys

1. Go to Settings → API Keys
2. Click Create API Key
3. Give it a descriptive name
4. Select permissions
5. Copy the key (shown only once!)

Caution

API keys are shown only once. Store them securely immediately after creation.

Using API Keys

Include in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.futurity.work/v1/workflows

API Key Permissions

When creating an API key, select what it can access:

• Full access (all permissions)
• Read-only
• Specific resources (Vault, Workflows, etc.)

Managing API Keys

Action	How
View keys	Settings → API Keys
Revoke key	Click the key → Revoke
Rotate key	Revoke and create new

Using Tokens

Request Header

All authenticated requests need the Authorization header:

Authorization: Bearer YOUR_TOKEN

Example Requests

Get current user:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.futurity.work/v1/whoami

Create a workflow:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Workflow"}' \
  https://api.futurity.work/v1/workflows

Error Handling

Invalid Token

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token"
  }
}

Solution: Refresh the token or re-authenticate.

Insufficient Scope

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Token does not have required scope: workflows"
  }
}

Solution: Request additional scopes during authorization.

Rate Limited

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "retryAfter": 60
  }
}

Solution: Wait and retry with exponential backoff.

Security Best Practices

1. Never expose tokens in client-side code: Use server-side handling
2. Store securely: Use environment variables or secrets managers
3. Rotate regularly: Especially API keys for production
4. Revoke immediately: When compromised or no longer needed
5. Use minimum scopes: Only request what you need
6. Validate state parameter: Prevent CSRF in OAuth flow

Registering Your Application

To use OAuth, register your application:

1. Go to Settings → Developer
2. Click Register Application
3. Fill in application details:
   • Name
   • Description
   • Redirect URIs
   • Scopes needed
4. Receive client_id and client_secret

Testing Authentication

Verify your token works:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.futurity.work/v1/whoami

Expected response:

{
  "data": {
    "id": "user_123",
    "email": "you@example.com",
    "name": "Your Name"
  }
}

Next Steps

• API Reference
• API Overview