Scopes and Permissions¶

Scopes define what actions can be performed with your API keys and service actors.

Understanding Scopes¶

Scopes are permissions that:

• Control what resources can be accessed
• Define what operations can be performed
• Determine which features are available
• Follow a category:action format (e.g., analytics:query)

API Keys vs Service Actors: Scope Usage¶

Important: Scopes work differently for API keys and service actors:

• API Keys: Use scopes to provision and manage resources (create organizations, create service actors, exchange tokens)
• Service Actors: Use capabilities (which are scopes) to access data and services (query analytics, read brain data, manage connectors)

API Key Scopes¶

API keys are used for provisioning and management operations. Common API key scope combinations:

Basic CI/CD Deployer (create service actors and exchange tokens):

{
  "name": "ci-deployer",
  "scopes": [
    "provision:service:create",
    "provision:token:exchange"
  ]
}

Full Provisioning Access (create orgs, manage service actors, exchange tokens):

{
  "name": "full-provisioner",
  "scopes": [
    "provision:org:create",
    "provision:service:create",
    "provision:service:read",
    "provision:service:update",
    "provision:service:delete",
    "provision:token:exchange",
    "provision:credentials:rotate"
  ]
}

Organization Management (create and read organizations):

{
  "name": "org-manager",
  "scopes": [
    "provision:org:create",
    "provision:org:read"
  ]
}

Service Actor Capabilities¶

Service actors use capabilities (which are the same as scopes) to access data and services. These capabilities are assigned when creating the service actor:

Analytics Service Actor:

{
  "name": "Analytics Service Actor",
  "capabilities": [
    "analytics:query",
    "analytics:read",
    "analytics:write"
  ]
}

Brain Service Actor:

{
  "name": "Brain Service Actor",
  "capabilities": [
    "brain:read",
    "brain:write"
  ]
}

Connector Service Actor:

{
  "name": "Connector Service Actor",
  "capabilities": [
    "connectors:read",
    "connectors:write",
    "connectors:sync"
  ]
}

Scope Categories¶

1. Provisioning Scopes¶

Provisioning scopes control the creation and management of resources. These are used with API keys for provisioning operations.

2. Analytics Scopes¶

Analytics scopes control access to analytics features and data. These are used as service actor capabilities for data access.

3. Brain Scopes¶

Brain scopes control access to AI/brain services. These are used as service actor capabilities for AI operations.

4. Data Connector Scopes¶

Data connector scopes control access to data connector features. These are used as service actor capabilities for connector operations.

Note: Data connector scopes may vary as features are developed.

Requesting Scopes¶

When Creating API Keys¶

API keys require provisioning scopes to manage resources. You must specify at least one scope:

Example: CI/CD Deployer API Key

curl -X POST https://api.fermi.dev/public/v1/identity/api-keys \
  -H "Authorization: Bearer <your-user-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-deployer",
    "scopes": [
      "provision:service:create",
      "provision:token:exchange",
      "provision:org:create"
    ],
    "expiresAt": "2026-01-01T00:00:00Z"
  }'

Example: Organization Manager API Key

curl -X POST https://api.fermi.dev/public/v1/identity/api-keys \
  -H "Authorization: Bearer <your-user-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "org-manager",
    "scopes": [
      "provision:org:create",
      "provision:org:read"
    ]
  }'

When Creating Service Actors¶

Service actors use "capabilities" (which are scopes) for data access. These are assigned when creating the service actor:

curl -X POST https://api.fermi.dev/public/v1/identity/service-actors \
  -H "Authorization: Bearer fmk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics Service Actor",
    "organisationId": "507f1f77bcf86cd799439011",
    "capabilities": [
      "analytics:query",
      "analytics:write"
    ]
  }'

Note: The API key used to create the service actor must have provision:service:create scope, but the service actor's capabilities determine what data/services it can access.

When Rotating API Keys¶

You can update scopes when rotating an API key:

curl -X POST https://api.fermi.dev/public/v1/identity/api-keys/{key-id}/rotate \
  -H "Authorization: Bearer <your-user-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": [
      "provision:service:create",
      "provision:token:exchange",
      "provision:org:create"
    ]
  }'

Scope Validation¶

How Scopes are Validated¶

1. API Key Validation: When you make a request with an API key, the system checks if the key has the required scope
2. Service Actor Validation: Service actor tokens include scopes from the service actor's capabilities
3. Endpoint Requirements: Some endpoints require specific scopes

Scope Errors¶

If you attempt to use an endpoint without the required scope:

{
  "status": 403,
  "error": "Forbidden",
  "message": "Missing required scope: analytics:query"
}

Solution: - For API keys: Create a new API key or rotate your existing key to include the required scope - For service actors: Update the service actor's capabilities to include the required scope

Scope Inheritance¶

Service Actor Tokens¶

When you exchange an API key for a service actor token:

• The token inherits scopes from the service actor's capabilities
• The API key must have provision:token:exchange scope
• The service actor's capabilities determine what the token can do

Example:

// Service actor with capabilities
{
  "id": "actor-123",
  "capabilities": ["analytics:query", "analytics:write"]
}

// Token exchange response
{
  "token": "...",
  "scopes": ["analytics:query", "analytics:write"]  // Inherited from service actor
}

Common Scope Combinations¶

API Key Combinations¶

CI/CD Pipeline API Key:

{
  "scopes": [
    "provision:service:create",
    "provision:token:exchange",
    "provision:org:create"
  ]
}

Service Actor Management API Key:

{
  "scopes": [
    "provision:service:create",
    "provision:service:read",
    "provision:service:update",
    "provision:service:delete",
    "provision:token:exchange"
  ]
}

Full Provisioning Access API Key:

{
  "scopes": [
    "provision:org:create",
    "provision:org:read",
    "provision:service:create",
    "provision:service:read",
    "provision:service:update",
    "provision:service:delete",
    "provision:token:exchange",
    "provision:credentials:rotate"
  ]
}

Service Actor Capability Combinations¶

Analytics Integration:

{
  "capabilities": [
    "analytics:query",
    "analytics:read"
  ]
}

Full Analytics Access:

{
  "capabilities": [
    "analytics:query",
    "analytics:read",
    "analytics:write"
  ]
}

Multi-Service Access:

{
  "capabilities": [
    "analytics:query",
    "analytics:read",
    "brain:read",
    "connectors:read",
    "connectors:write"
  ]
}

Scope Errors and Troubleshooting¶

Error: Missing Required Scope¶

{
  "status": 403,
  "error": "Forbidden",
  "message": "Missing required scope: analytics:query"
}

Solutions:

1. For API Keys:
2. Check your API key has the required scope
3. Create a new API key with the scope

4. Rotate your existing key to add the scope

5. For Service Actors:

6. Update the service actor's capabilities to include the required scope
7. Create a new service actor with the required capabilities

Error: Invalid Scope¶

{
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid scope: invalid:scope"
}

Solution: Verify the scope name is correct. Check the scope reference for valid scopes.

Error: Scope Not Available¶

{
  "status": 403,
  "error": "Forbidden",
  "message": "Scope not available for your organization"
}

Solution: Some scopes may require specific organization features or plans. Contact support if you need access to restricted scopes.

Examples¶

Creating API Key for CI/CD¶

import requests

response = requests.post(
    "https://api.fermi.dev/public/v1/identity/api-keys",
    headers={
        "Authorization": f"Bearer {user_jwt_token}",
        "Content-Type": "application/json"
    },
    json={
        "name": "ci-deployer",
        "scopes": [
            "provision:service:create",
            "provision:token:exchange",
            "provision:org:create"
        ],
        "expiresAt": "2026-01-01T00:00:00Z"
    }
)

api_key_data = response.json()
print(f"Created API key: {api_key_data['apiKey']}")
print(f"Scopes: {api_key_data['scopes']}")

Creating Service Actor with Analytics Capabilities¶

import requests

api_key = "fmk_live_your_api_key"
org_id = "your-org-id"

response = requests.post(
    "https://api.fermi.dev/public/v1/identity/service-actors",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Analytics Service Actor",
        "organisationId": org_id,
        "capabilities": [
            "analytics:query",
            "analytics:read",
            "analytics:write"
        ]
    }
)

service_actor = response.json()
print(f"Created service actor: {service_actor['data']['id']}")
print(f"Capabilities: {service_actor['data']['capabilities']}")

Checking Required Scopes¶

Before making an API call, you can check what scopes are required by reviewing the API documentation or testing with a key that has limited scopes.

Validating Scopes¶

def validate_scope(api_key, required_scope):
    """Check if API key has required scope"""
    # Make a test request to verify scope
    response = requests.get(
        "https://api.fermi.dev/public/v1/identity/service-actors",
        headers={"Authorization": f"Bearer {api_key}"}
    )

    if response.status_code == 403:
        error = response.json()
        if required_scope in error.get("message", ""):
            return False

    return response.status_code == 200

Scope Reference Summary¶

Next Steps¶

• API Keys - Learn how to create and manage API keys with scopes
• Service Actors - Understand service actor capabilities
• Token Exchange - See how scopes work with token exchange
• API Reference - Check endpoint scope requirements