Skip to main content

​
Managing API Keys

API keys provide a secure way to authenticate programmatic access to your Orquestra projects. This guide covers creating, using, and managing API keys.

​
Overview

API keys are project-specific credentials that allow:
  • Authentication for protected endpoints
  • Usage tracking and monitoring
  • Access control and permissions
  • Integration with CI/CD pipelines
Currently, public endpoints (like building transactions) don’t require API keys. API keys are primarily used for accessing private projects and future premium features.

​
Creating API Keys in the Dashboard

1

Open Your Project

Navigate to your project in the Orquestra dashboard
2

Go to API Keys Section

Click on Settings > API Keys
3

Create New Key

Click Generate New API KeyOptionally, set an expiration date (e.g., 90 days, 1 year, or never)
4

Save Your Key

Important: Copy and store your API key immediately. It will only be shown once!The key format is: b58_ followed by 64 hexadecimal characters
Treat API keys like passwords. Never commit them to version control or share them publicly.

​
Creating API Keys via API

You can programmatically create API keys using your JWT token: 
curl -X POST https://api.orquestra.so/api/projects/{projectId}/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expiresInDays": 90
  }'

​
Response

{
  "id": "key_abc123",
  "key": "b58_a1b2c3d4e5f6...",
  "createdAt": "2024-03-15T10:30:00Z",
  "expiresAt": "2024-06-13T10:30:00Z",
  "message": "Store this key securely. It will not be shown again."
}
If you don’t specify expiresInDays, the key will never expire. However, it’s a best practice to rotate keys periodically.

​
Using API Keys for Authentication

API keys are sent via the X-API-Key header: 
curl https://api.orquestra.so/api/projects \
  -H "X-API-Key: b58_a1b2c3d4e5f6..."

​
When to Use API Keys vs JWT

Use CaseAuthentication Method
User actions in web appJWT (Bearer token)
Server-side integrationsAPI Key
CI/CD pipelinesAPI Key
Mobile/desktop appsJWT (OAuth flow)
Cron jobs & scriptsAPI Key

​
Listing Your API Keys

View all API keys for a project: 
curl https://api.orquestra.so/api/projects/{projectId}/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "keys": [
    {
      "id": "key_abc123",
      "key": "************************a1b2c3d4",
      "last_used": "2024-03-15T14:20:00Z",
      "created_at": "2024-03-01T10:30:00Z",
      "expires_at": "2024-06-13T10:30:00Z"
    },
    {
      "id": "key_xyz789",
      "key": "************************9z8y7x6w",
      "last_used": null,
      "created_at": "2024-03-10T08:15:00Z",
      "expires_at": null
    }
  ]
}
For security, only the last 8 characters of each key are shown. The full key is only visible when first created.

​
Rotating API Keys

Rotate a key to generate a new value while keeping the same key ID: 
curl -X POST https://api.orquestra.so/api/projects/{projectId}/keys/{keyId}/rotate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "id": "key_abc123",
  "key": "b58_new_rotated_key...",
  "message": "API key rotated successfully. Store the new key — it will not be shown again."
}
Use rotation to replace compromised keys without updating your configuration IDs.

​
Deleting API Keys

Revoke an API key permanently: 
curl -X DELETE https://api.orquestra.so/api/projects/{projectId}/keys/{keyId} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "message": "API key deleted"
}
Deleting a key immediately revokes access. Any applications using this key will fail authentication.

​
Rate Limits and Permissions

​
Rate Limits

API keys share the same rate limits as unauthenticated requests:
Endpoint TypeRate Limit
General API100 requests/minute
Transaction building30 requests/minute
IDL uploads10 requests/minute
Authentication20 requests/minute
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 25
X-RateLimit-Reset: 1710504600
Retry-After: 45 (when rate limited)

​
Handling Rate Limits

function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function makeRequestWithRetry(url: string, apiKey: string) {
  const response = await fetch(url, {
    headers: { 'X-API-Key': apiKey },
  });

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
    console.log(`Rate limited. Retrying after ${retryAfter}s...`);
    await sleep(retryAfter * 1000);
    return makeRequestWithRetry(url, apiKey);
  }

  return response;
}

​
Permissions

API keys inherit the permissions of the project owner. They can: ✅ Build transactions for the project
✅ Access project metadata
✅ List instructions and accounts
✅ Derive PDAs
✅ Retrieve documentation API keys cannot: ❌ Delete the project
❌ Modify project settings
❌ Create/delete other API keys
❌ Access other users’ projects
Future updates may include granular permission controls for API keys.

​
Best Practices

​
Security

  1. Use environment variables: Never hardcode API keys 
    export ORQUESTRA_API_KEY="b58_..."
  2. Rotate regularly: Set expiration dates and rotate keys every 90 days
  3. Limit scope: Create separate keys for different applications
  4. Monitor usage: Check last_used timestamps to detect unusual activity
  5. Revoke unused keys: Delete keys that haven’t been used in 30+ days

​
Development Workflow

.env.example
# .env.example (commit this)
ORQUESTRA_API_KEY=your_key_here

# .env (add to .gitignore)
ORQUESTRA_API_KEY=b58_a1b2c3d4e5f6...
TypeScript
import * as dotenv from 'dotenv';
dotenv.config();

const apiKey = process.env.ORQUESTRA_API_KEY;
if (!apiKey) {
  throw new Error('ORQUESTRA_API_KEY not set');
}

​
CI/CD Integration

name: Deploy
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Build transaction
        env:
          ORQUESTRA_API_KEY: ${{ secrets.ORQUESTRA_API_KEY }}
        run: |
          curl -X POST https://api.orquestra.so/api/$PROJECT_ID/instructions/deploy/build \
            -H "X-API-Key: $ORQUESTRA_API_KEY" \
            -d @transaction.json

​
Troubleshooting

​
”Invalid or expired API key”

  • Check that the key is copied correctly (no extra spaces)
  • Verify the key hasn’t expired
  • Ensure you’re using X-API-Key header (not Authorization)

​
“Project not found or access denied”

  • Confirm the project ID is correct
  • Verify the API key belongs to the project owner
  • Check that the project hasn’t been deleted

​
High rate limit errors

  • Implement exponential backoff
  • Cache frequently accessed data
  • Consider batching requests

​
Next Steps

Building Transactions

Use your API key to build transactions programmatically

Uploading IDLs

Learn about IDL management

API Reference

Full API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us