Skip to main content

API Key Scopes

Scopes control what actions an API key can perform. Use the principle of least privilege: grant only the scopes required for the specific use case.

Available Scopes​

sessions:read​

View session information.

Grants access to:

  • GET /api/v1/sessions - List all sessions
  • GET /api/v1/sessions/{id} - Get session details

Use cases:

  • Monitoring active sessions
  • Audit and compliance reporting
  • Dashboard integrations

sessions:write​

Create, modify, and delete sessions.

Grants access to:

  • POST /api/v1/sessions - Start a new session
  • POST /api/v1/sessions/{id}/stop - Stop a session
  • POST /api/v1/sessions/{id}/extend - Extend session duration

Use cases:

  • CI/CD pipelines that need temporary IP access
  • Automated session management scripts
  • Integration tests

Note: sessions:write does not include sessions:read. To both read and write sessions, grant both scopes.

resources:read​

View resource information.

Grants access to:

  • GET /api/v1/resources - List all resources
  • GET /api/v1/resources/{id} - Get resource details

Use cases:

  • Inventory management
  • Resource discovery for automation
  • Integration with asset management systems

audit:read​

View audit logs.

Grants access to:

  • GET /api/v1/audit-logs - List audit logs (with pagination and filtering)

Use cases:

  • Security information and event management (SIEM) integration
  • Compliance reporting
  • Security audits

Scope Combinations​

You can grant multiple scopes to a single API key:

curl -X POST https://api.entryguard.io/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Full Access",
    "scopes": ["sessions:read", "sessions:write", "resources:read"]
  }'

Endpoint Protection​

Not all endpoints support API key authentication. Only endpoints annotated with @RequiresScope can be accessed via API keys.

Currently unsupported endpoints:

  • User management (/users)
  • Role management (/roles)
  • Credential management (/credentials)
  • Organization settings (/organization)
  • MFA endpoints (/mfa)
  • Static IP rules (/static-ip-rules)

These endpoints require user authentication via Authorization: Bearer tokens.

Scope Validation​

When an API key is used:

  1. The system extracts the key from the X-API-Key header
  2. Validates the key exists and is not expired
  3. Checks if the endpoint requires a specific scope
  4. Grants or denies access based on the key's scopes

If a key lacks the required scope, the request returns 403 Forbidden:

{
  "error": "Insufficient permissions",
  "message": "API key does not have required scope: sessions:write"
}

Best Practices​

Minimal Scopes​

Only grant scopes that are absolutely necessary. For example:

  • Read-only monitoring: Use only sessions:read and resources:read
  • CI/CD session management: Use sessions:write (and sessions:read if you need to verify session status)
  • Compliance reporting: Use only audit:read

Separate Keys for Different Services​

Create dedicated keys for each service or pipeline:

# Key for monitoring dashboard
curl -X POST https://api.entryguard.io/api/v1/api-keys \
  -d '{"name": "Dashboard", "scopes": ["sessions:read", "resources:read"]}'

# Key for CI/CD
curl -X POST https://api.entryguard.io/api/v1/api-keys \
  -d '{"name": "GitHub Actions", "scopes": ["sessions:write"]}'

# Key for audit log export
curl -X POST https://api.entryguard.io/api/v1/api-keys \
  -d '{"name": "SIEM Integration", "scopes": ["audit:read"]}'

This approach:

  • Limits blast radius if a key is compromised
  • Makes it easier to rotate keys for specific services
  • Provides clearer audit trails

Future Scopes​

Additional scopes may be added in future releases:

  • resources:write - Create and modify resources
  • users:read - View user information
  • roles:read - View roles
  • credentials:read - View credentials (without secrets)

Check the API documentation for the latest scope availability.

Next Steps​