Authentication

Learn how to authenticate your API requests using API keys and integrate with Yapture's OAuth 2.0 system.

API Key Authentication

All developer API endpoints require authentication using an API key. API keys are passed in the Authorization header as a Bearer token.

Generating an API Key

After registering as a developer, generate your first API key:

curl -X POST https://yapture.market/api/dev/api-keys \
  -H "Authorization: Bearer YOUR_EXISTING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "scopes": ["APP_CREATE", "APP_READ", "APP_UPDATE", "APP_DELETE"],
    "expiresInDays": 365
  }'

Response:

{
  "apiKey": "yk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "id": "clxxxxxxxx",
  "name": "Production Key",
  "keyPrefix": "yk_12345",
  "scopes": ["APP_CREATE", "APP_READ", "APP_UPDATE", "APP_DELETE"],
  "expiresAt": "2026-09-30T00:00:00.000Z",
  "createdAt": "2025-09-30T00:00:00.000Z"
}

⚠️ Important

The full API key is only shown once during creation. Store it securely! You'll only see the key prefix (first 8 characters) in future API responses.

Using Your API Key

Include your API key in the Authorization header of all requests:

curl https://yapture.market/api/dev/apps \
  -H "Authorization: Bearer yk_1234567890abcdef..."

API Key Scopes

Control what your API keys can access by specifying scopes:

Scope	Description
APP_CREATE	Create new app listings
APP_READ	Read app data and details
APP_UPDATE	Update app information
APP_DELETE	Delete apps (draft/rejected only)
ANALYTICS_READ	Access analytics and metrics

Managing API Keys

List all your API keys:

curl https://yapture.market/api/dev/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY"

Revoke an API key:

curl -X DELETE https://yapture.market/api/dev/api-keys/{KEY_ID} \
  -H "Authorization: Bearer YOUR_API_KEY"

OAuth 2.0 Integration

If your app needs to access user data in Yapture, you'll need to integrate with our OAuth 2.0 system using PKCE (Proof Key for Code Exchange) for enhanced security.

OAuth Flow Overview

User clicks "Install" on your app in Yapture Market
User is redirected to Yapture's authorization page
User approves the requested permissions
User is redirected back to your app with an authorization code
Your app exchanges the code for an access token
Your app uses the access token to make API calls on behalf of the user

Registering Your OAuth Client

When creating or updating your app, specify an oauthClientId to link it with an OAuth client configured in the Admin Portal. Contact support to set up your OAuth client with:

Redirect URIs - Allowed callback URLs for your app
Scopes - Permissions your app requests (e.g., tasks:read, tasks:write)
Environment - Development, staging, or production

Example OAuth Flow with PKCE

Step 1: Generate PKCE code verifier and challenge

// Generate random code verifier
const codeVerifier = generateRandomString(128);

// Create SHA256 hash and base64url encode
const codeChallenge = base64UrlEncode(
  sha256(codeVerifier)
);

Step 2: Redirect user to authorization URL

const authUrl = new URL('https://yapture.com/oauth/authorize');
authUrl.searchParams.set('client_id', 'your_client_id');
authUrl.searchParams.set('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'tasks:read tasks:write');
authUrl.searchParams.set('code_challenge', codeChallenge);
authUrl.searchParams.set('code_challenge_method', 'S256');

window.location.href = authUrl.toString();

Step 3: Exchange authorization code for access token

const response = await fetch('https://yapture.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    client_id: 'your_client_id',
    code: authorizationCode,
    code_verifier: codeVerifier,
    redirect_uri: 'https://yourapp.com/callback'
  })
});

const { access_token, refresh_token } = await response.json();

Step 4: Use access token to make API calls

const tasks = await fetch('https://yapture.com/api/tasks', {
  headers: {
    'Authorization': `Bearer ${access_token}`
  }
}).then(r => r.json());

Security Best Practices

Store API keys securely

Never commit API keys to version control. Use environment variables or secret management systems.

Rotate keys regularly

Generate new API keys periodically and revoke old ones to minimize security risks.

Use minimal scopes

Only request the permissions your app actually needs. Don't use overly broad scopes.

Implement PKCE for OAuth

Always use PKCE (Proof Key for Code Exchange) to prevent authorization code interception attacks.

Handle tokens securely

Store access tokens securely, use HTTPS for all API calls, and implement token refresh logic.

Error Handling

Common authentication errors:

Status Code	Error	Solution
401	Unauthorized	Check your API key is correct and active
403	Forbidden	Your API key lacks required scopes
429	Rate Limited	Wait before retrying, implement exponential backoff