Skip to main content

Authentication

OfSelf supports two authentication methods: API Keys for server-to-server calls and OAuth 2.0 for user-facing applications.

API Key Authentication​

API Keys are the simplest way to authenticate. Use them for:

  • Backend services
  • Scripts and automation
  • Testing and development

Using API Keys​

Include your API key in the X-API-Key header:

curl -X GET "https://api.ofself.ai/api/v1/nodes" \
  -H "X-API-Key: ofs_key_xxxxxxxxxxxxx" \
  -H "X-User-ID: user-123"
X-User-ID Header

When using API keys, you must specify which user's data you're accessing with the X-User-ID header. You can only access data for users who have authorized your app.

Python SDK​

from ofself import OfSelfClient

client = OfSelfClient(api_key="ofs_key_xxxxxxxxxxxxx")

# Access user's data
nodes = client.nodes.list(user_id="user-123")

JavaScript SDK​

import { OfSelfClient } from '@ofself/sdk';

const client = new OfSelfClient({
  apiKey: 'ofs_key_xxxxxxxxxxxxx'
});

const nodes = await client.nodes.list({ userId: 'user-123' });

OAuth 2.0 Authentication​

Use OAuth when:

  • Building web/mobile apps
  • Users need to "Connect with OfSelf"
  • You want user-specific access tokens

OAuth Flow​

┌─────────┐                              ┌─────────┐                              ┌─────────┐
│  User   │                              │Your App │                              │ OfSelf  │
└────┬────┘                              └────┬────┘                              └────┬────┘
     │                                        │                                        │
     │  1. Click "Connect OfSelf"             │                                        │
     │───────────────────────────────────────>│                                        │
     │                                        │                                        │
     │                                        │  2. Redirect to authorization          │
     │<───────────────────────────────────────│───────────────────────────────────────>│
     │                                        │                                        │
     │  3. User reviews permissions           │                                        │
     │<───────────────────────────────────────────────────────────────────────────────>│
     │                                        │                                        │
     │  4. User approves                      │                                        │
     │───────────────────────────────────────────────────────────────────────────────>│
     │                                        │                                        │
     │                                        │  5. Redirect with code                 │
     │<───────────────────────────────────────│<───────────────────────────────────────│
     │                                        │                                        │
     │                                        │  6. Exchange code for tokens           │
     │                                        │───────────────────────────────────────>│
     │                                        │                                        │
     │                                        │  7. Return access_token                │
     │                                        │<───────────────────────────────────────│
     │                                        │                                        │

Step 1: Authorization URL​

Redirect users to the OfSelf authorization page:

https://api.ofself.ai/oauth/authorize
  ?client_id=ofs_client_xxxxxxxxxxxxx
  &redirect_uri=https://myapp.com/callback
  &response_type=code
  &scope=nodes:read tags:read
  &state=random-state-string
ParameterDescription
client_idYour app's client ID
redirect_uriWhere to redirect after authorization
response_typeAlways code
scopePermissions requested (space-separated)
stateRandom string to prevent CSRF

Step 2: Handle Callback​

After approval, user is redirected to your redirect_uri:

https://myapp.com/callback
  ?code=authorization_code_here
  &state=random-state-string

Step 3: Exchange Code for Tokens​

curl -X POST "https://api.ofself.ai/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=ofs_client_xxxxxxxxxxxxx" \
  -d "client_secret=ofs_secret_xxxxxxxxxxxxx" \
  -d "code=authorization_code_here" \
  -d "redirect_uri=https://myapp.com/callback"

Response:

{
  "access_token": "ofs_access_xxxxxxxxxxxxx",
  "refresh_token": "ofs_refresh_xxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600
}

Step 4: Use Access Token​

curl -X GET "https://api.ofself.ai/api/v1/nodes" \
  -H "Authorization: Bearer ofs_access_xxxxxxxxxxxxx"
No X-User-ID Needed

With OAuth tokens, the user is already identified. No need for X-User-ID header.

Refreshing Tokens​

Access tokens expire after 1 hour. Use the refresh token to get new ones:

curl -X POST "https://api.ofself.ai/oauth/token" \
  -d "grant_type=refresh_token" \
  -d "client_id=ofs_client_xxxxxxxxxxxxx" \
  -d "client_secret=ofs_secret_xxxxxxxxxxxxx" \
  -d "refresh_token=ofs_refresh_xxxxxxxxxxxxx"

OAuth Scopes​

ScopeDescription
nodes:readRead user's nodes
nodes:writeCreate, update, delete nodes
tags:readRead user's tags
tags:writeCreate, update, delete tags
files:readRead user's files
files:writeUpload, update, delete files
relationships:readRead node relationships
relationships:writeCreate, update, delete relationships
proposals:writeCreate proposals

Request only the scopes you need. Users are more likely to approve apps that request minimal permissions.

Security Best Practices​

  1. Never expose secrets - Keep client_secret and API keys server-side
  2. Use HTTPS - All OfSelf endpoints require HTTPS
  3. Validate state - Prevent CSRF by checking the state parameter
  4. Store tokens securely - Encrypt tokens at rest
  5. Implement token refresh - Handle expired access tokens gracefully

Next Steps​