Authentication

The Flybox API uses Bearer token authentication to secure all endpoints. This guide covers how to authenticate your requests and manage API keys.

Authentication Header

All authenticated requests must include the Authorization header with a valid Bearer token:

Authorization: Bearer YOUR_API_KEY

Obtaining API Keys

Via Dashboard

1. Log in to Flybox Dashboard
2. Navigate to Settings → API Keys
3. Click Generate New Key
4. Provide a descriptive name for the key
5. Select the appropriate permissions
6. Click Create

Note: The full API key is only shown once. Make sure to copy and store it securely.

Via API

You can also create API keys programmatically (requires an existing authenticated session):

mutation CreateAPIKey($input: CreateAPIKeyInput!) {
  createAPIKey(input: $input) {
    id
    key
    name
    createdAt
    expiresAt
  }
}

Variables:

{
  "input": {
    "name": "CI/CD Pipeline",
    "permissions": ["READ", "WRITE"],
    "expiresIn": "30d"
  }
}

API Key Types

Code Examples

cURL

curl -X POST https://api.flybox.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fb_live_xxxxxxxxxxxx" \
  -d '{"query": "{ viewer { id email } }"}'

JavaScript (fetch)

const response = await fetch('https://api.flybox.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.FLYBOX_API_KEY}`,
  },
  body: JSON.stringify({
    query: `
      query GetViewer {
        viewer {
          id
          email
          name
        }
      }
    `,
  }),
});

const data = await response.json();

Python (requests)

import os
import requests

FLYBOX_API_KEY = os.environ.get('FLYBOX_API_KEY')

response = requests.post(
    'https://api.flybox.com/graphql',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {FLYBOX_API_KEY}',
    },
    json={
        'query': '''
            query GetViewer {
                viewer {
                    id
                    email
                    name
                }
            }
        '''
    }
)

data = response.json()

Apollo Client (TypeScript)

import { ApolloClient, InMemoryCache, createHttpLink } from '@apollo/client';
import { setContext } from '@apollo/client/link/context';

const httpLink = createHttpLink({
  uri: 'https://api.flybox.com/graphql',
});

const authLink = setContext((_, { headers }) => {
  return {
    headers: {
      ...headers,
      authorization: `Bearer ${process.env.FLYBOX_API_KEY}`,
    },
  };
});

const client = new ApolloClient({
  link: authLink.concat(httpLink),
  cache: new InMemoryCache(),
});

Security Best Practices

Do ✅

• Store API keys in environment variables
• Use separate keys for different environments (dev, staging, prod)
• Rotate keys regularly
• Set appropriate expiration dates
• Use the principle of least privilege (minimal required permissions)

Don't ❌

• Commit API keys to version control
• Expose keys in client-side code
• Share keys via insecure channels (email, Slack)
• Use production keys for development

Key Rotation

To rotate an API key without downtime:

1. Generate a new API key
2. Update your application to use the new key
3. Verify the new key works correctly
4. Revoke the old key

mutation RevokeAPIKey($id: ID!) {
  revokeAPIKey(id: $id) {
    id
    revokedAt
  }
}

Troubleshooting

"UNAUTHENTICATED" Error

{
  "errors": [{
    "message": "You must be authenticated to perform this action",
    "extensions": { "code": "UNAUTHENTICATED" }
  }]
}

Possible causes:

• Missing Authorization header
• Malformed token (check for extra spaces or characters)
• Expired API key
• Revoked API key

"FORBIDDEN" Error

{
  "errors": [{
    "message": "You do not have permission to perform this action",
    "extensions": { "code": "FORBIDDEN" }
  }]
}

Possible causes:

• API key lacks required permissions
• Resource belongs to a different organization
• Action requires elevated privileges

Next Steps

• GraphQL API Reference - Explore available queries and mutations