Skip to main content

Authentication

All API requests from third-party apps require authentication using an API key.

Important: API Key Authentication Only

Third-party developers must use API Key + X-User-ID authentication. User JWT authentication (login with email/password) is exclusively for app.ofself.ai and is NOT available to third-party apps.

How App Authentication Works​

When your app makes an API call, the SDK validates the API key, looks up the user's Exposure Profile, and returns only authorized data.

API Request Flow

How third-party API calls are authenticated and filtered

1. Your App
Send request with X-API-Key and X-User-ID headers
2. SDK validates credentials
Parses API key, verifies against stored hash, confirms app is registered
Valid?
401
↓ Yes
3. Exposure Profile applied
Loads the user’s Exposure Profile for this app and filters query results — only authorized Nodes, Relationships, and Tags returned
200 OK
4. Filtered response
App receives only the data the user authorized via their Exposure Profile

Key

X-API-Key
Your app’s API key from registration
X-User-ID
UUID of the user who authorized your app
Exposure Profile
User-defined filter — controls what data your app can see

API Key Authentication​

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_tp_xxxxxxxxxxxx.yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy" \
  -H "X-User-ID: user-123"
User ID Header

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

Getting an API Key​

  1. Register your app at the developer portal
  2. Your API key will be provided once during registration
  3. Store it securely - it cannot be retrieved again

Getting a User ID​

Before you can make API calls on behalf of a user, the user must authorize your app through the authorization flow. After approval, your callback URL receives the user_id:

https://yourapp.com/callback?code=success&client_id=tp_...&user_id=<uuid>

Store this user_id and use it in the X-User-ID header for all subsequent requests.

For the full authorization flow, see the Authentication getting started guide.

Error Responses​

401 Unauthorized​

{
  "error": "Invalid API key",
  "status_code": 401
}

403 Forbidden​

{
  "error": "User has not authorized this app",
  "status_code": 403
}