Authentication

Learn how to authenticate with the AIDP Platform API.

Overview

AIDP uses JWT (JSON Web Tokens) for authentication. All API requests require a valid API key or JWT token.

Authentication Flow

JWT Authentication Flow

Getting an API Key

1. Sign Up

Create an account at platform.aidp.dev

2. Generate API Key

1. Navigate to Settings → API Keys

2. Click Create New API Key

3. Give it a descriptive name (e.g., "Production API")

4. Copy the key immediately (it won't be shown again)

5. Store securely (never commit to version control)

3. Use API Key

Include in the Authorization header:

curl -H "Authorization: Bearer sk_live_abc123..." \
  https://api.aidp.dev/v1/businesses/search

API Key Types

Test Keys

For development and testing:

sk_test_abc123...

Characteristics:

• Access to sandbox environment

• No real charges

• Rate limited (100 req/hour)

• Test data only

Live Keys

For production use:

sk_live_abc123...

Characteristics:

• Access to production environment

• Real charges apply

• Higher rate limits

• Real data

Authentication Methods

1. API Key (Recommended)

Simple and secure for server-to-server communication.

TypeScript:

import { AIDPClient } from '@aidp/sdk';

const client = new AIDPClient({
  apiKey: process.env.AIDP_API_KEY,
});

Python:

from aidp import AIDPClient

client = AIDPClient(api_key=os.environ['AIDP_API_KEY'])

cURL:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.aidp.dev/v1/businesses/search

2. JWT Tokens

For user-specific authentication (web/mobile apps).

Login:

POST /auth/login
Content-Type: application/json

{
  "email": "[e-mail]",
  "password": "secure_password"
}

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 3600
  }
}

Use Token:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.aidp.dev/v1/business/profile

3. OAuth 2.0

For third-party integrations.

Authorization URL:

https://platform.aidp.dev/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=read:businesses write:bookings

Exchange Code for Token:

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "https://yourapp.com/callback"
}

Token Refresh

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

POST /auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 3600
  }
}

Scopes

Control access with OAuth scopes:

Scope	Description
read:businesses	Read business profiles
write:businesses	Create/update profiles
read:bookings	View bookings
write:bookings	Create/manage bookings
read:analytics	Access analytics data
read:reviews	View reviews
write:reviews	Submit reviews

Example:

scope=read:businesses write:bookings read:analytics

Security Best Practices

Storing API Keys

✅ Do:

• Use environment variables

• Use secret management services (AWS Secrets Manager, HashiCorp Vault)

• Rotate keys regularly

• Use different keys for dev/staging/prod

❌ Don't:

• Commit keys to version control

• Hardcode in source code

• Share keys via email/chat

• Use same key across environments

Example (.env):

# .env (add to .gitignore)
AIDP_API_KEY=sk_live_abc123...

Example (code):

// ✅ Good
const apiKey = process.env.AIDP_API_KEY;

// ❌ Bad
const apiKey = 'sk_live_abc123...';

Key Rotation

Rotate API keys regularly:

1. Generate new key

2. Update applications with new key

3. Test thoroughly

4. Revoke old key

Monitoring

Monitor API key usage:

• Track requests per key

• Set up alerts for unusual activity

• Review access logs regularly

Error Handling

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Causes:

• Missing Authorization header

• Invalid API key

• Expired token

• Revoked key

Solution:

• Check API key is correct

• Ensure header is included

• Refresh expired tokens

• Generate new key if revoked

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions"
  }
}

Causes:

• Missing required scope

• Account suspended

• Resource access denied

Solution:

• Check OAuth scopes

• Verify account status

• Ensure proper permissions

Rate Limiting

API keys have rate limits based on plan:

Plan	Rate Limit
Free	100 req/hour
Professional	1,000 req/hour
Enterprise	10,000 req/hour

Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1638360000

Learn more about rate limiting →

Examples

TypeScript/JavaScript

import { AIDPClient } from '@aidp/sdk';

// Using API key
const client = new AIDPClient({
  apiKey: process.env.AIDP_API_KEY,
  environment: 'production',
});

// Using JWT token
const client = new AIDPClient({
  accessToken: userToken,
  onTokenExpired: async () => {
    // Refresh token
    const newToken = await refreshToken(refreshToken);
    return newToken;
  },
});

Python

from aidp import AIDPClient
import os

# Using API key
client = AIDPClient(
    api_key=os.environ['AIDP_API_KEY'],
    environment='production'
)

# Using JWT token
client = AIDPClient(
    access_token=user_token,
    on_token_expired=lambda: refresh_token(refresh_token)
)

cURL

# Using API key
curl -H "Authorization: Bearer $AIDP_API_KEY" \
  https://api.aidp.dev/v1/businesses/search

# Using JWT token
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.aidp.dev/v1/business/profile

Testing

Sandbox Environment

Test authentication without affecting production:

Sandbox API: https://sandbox-api.aidp.dev/v1
Test API Key: sk_test_abc123...

Postman Collection

Import our Postman collection for easy testing:

# Download collection
curl -O https://api.aidp.dev/postman/collection.json

# Import into Postman
# Set environment variable: AIDP_API_KEY

Support

Need help with authentication?

• 📚 Documentation: API Reference

• 💬 GitHub Discussions: github.com/aidp/platform/discussions

• 📧 Email: [e-mail]

• 🐛 Issues: GitHub Issues

Next Steps

• API Reference

• Rate Limiting

• Error Handling

• Code Examples