Permissions Reference

Complete reference for OAuth2 scopes and permissions required for Big Picture API access.

OAuth2 Scopes

Big Picture uses OAuth2 scopes to control access to API endpoints. Each scope grants permission to perform specific operations.

Available Scopes

Scope	Description	Operations
ci:write	Create and manage releases	POST /v1/releases, POST /v1/releases/{id}/revoke
artifacts:write	Upload and manage artifacts	POST /v1/artifacts/uploads, POST /v1/artifacts/uploads/{id}/complete
mirrors:read	Read snapshot data	GET /v1/snapshots/latest, GET /v1/snapshots/{snapshotId}
license:read	Read license information	GET /v1/license/status
license:write	Manage license leases	POST /v1/license/lease, POST /v1/license/lease/renew, POST /v1/license/lease/release
admin:read	Read admin resources	GET /v1/tenants/{id}/policies, GET /v1/entitlements, GET /v1/mirrors/{id}/status
admin:write	Write admin resources	PUT /v1/tenants/{id}/policies/{policyId}, POST /v1/entitlements, PUT /v1/entitlements/{id}, POST /v1/mirrors

Scope Details

ci:write

Purpose: Create and manage software releases.

Required For:

• Creating new releases
• Revoking releases
• Managing release metadata

Endpoints:

• POST /v1/releases - Create release
• POST /v1/releases/{id}/revoke - Revoke release

Usage: Typically granted to CI/CD pipelines and release automation tools.

artifacts:write

Purpose: Upload and manage artifacts.

Required For:

• Initiating artifact uploads
• Completing artifact uploads
• Managing artifact metadata

Endpoints:

• POST /v1/artifacts/uploads - Initiate artifact upload
• POST /v1/artifacts/uploads/{id}/complete - Complete artifact upload

Usage: Typically granted to CI/CD pipelines and artifact management tools.

mirrors:read

Purpose: Read snapshot data for mirror synchronization.

Required For:

• Retrieving latest snapshot manifests
• Retrieving snapshot bundles
• Mirror synchronization operations

Endpoints:

• GET /v1/snapshots/latest - Get latest snapshot
• GET /v1/snapshots/{snapshotId} - Get snapshot bundle

Usage: Typically granted to mirror instances for synchronization.

Authentication: Can use mTLS instead of OAuth2 for mirror instances.

license:read

Purpose: Read license status and information.

Required For:

• Checking license status
• Viewing active leases
• Reading entitlement information

Endpoints:

• GET /v1/license/status - Get license status

Usage: Typically granted to license management tools and monitoring systems.

license:write

Purpose: Manage license leases.

Required For:

• Requesting license leases
• Renewing license leases
• Releasing license leases

Endpoints:

• POST /v1/license/lease - Request license lease
• POST /v1/license/lease/renew - Renew license lease
• POST /v1/license/lease/release - Release license lease

Usage: Typically granted to license servers and client applications.

Authentication: Can use mTLS instead of OAuth2 for license servers.

admin:read

Purpose: Read administrative resources.

Required For:

• Viewing tenant policies
• Listing entitlements
• Viewing mirror status
• Reading configuration

Endpoints:

• GET /v1/tenants/{id}/policies - Get tenant policies
• GET /v1/entitlements - List entitlements
• GET /v1/mirrors/{id}/status - Get mirror status
• GET /v1/keys - Get public keys

Usage: Typically granted to administrative tools and monitoring systems.

admin:write

Purpose: Create and modify administrative resources.

Required For:

• Creating and updating tenant policies
• Managing entitlements
• Creating and updating mirrors
• Managing service accounts

Endpoints:

• PUT /v1/tenants/{id}/policies/{policyId} - Update tenant policy
• POST /v1/entitlements - Create entitlement
• PUT /v1/entitlements/{id} - Update entitlement
• POST /v1/mirrors - Create mirror

Usage: Typically granted to administrative users and management tools.

Scope Combinations

Common scope combinations for different use cases:

CI/CD Pipeline

{
  "scopes": ["ci:write", "artifacts:write"]
}

Use Case: Automated release creation and artifact upload.

License Server

{
  "scopes": ["license:read", "license:write"]
}

Use Case: License server operations.

Alternative: Use mTLS authentication instead of OAuth2.

Mirror Instance

{
  "scopes": ["mirrors:read"]
}

Use Case: Mirror synchronization.

Alternative: Use mTLS authentication instead of OAuth2.

Administrative Tool

{
  "scopes": ["admin:read", "admin:write"]
}

Use Case: Full administrative access.

Read-Only Monitoring

{
  "scopes": ["admin:read", "license:read"]
}

Use Case: Monitoring and reporting without modification permissions.

Scope Format

In OAuth2 Token Requests:

• Space-separated list: ci:write artifacts:write
• Multiple scopes can be requested
• Server validates requested scopes against client permissions

In Service Account Configuration:

• Array format: ["ci:write", "artifacts:write"]
• JSON array in API requests

In API Responses:

• Array format: ["ci:write", "artifacts:write"]
• Included in token and service account responses

Scope Validation

Request Validation:

• Server validates requested scopes against client permissions
• Invalid scopes are rejected with invalid_scope error
• Unauthorized scopes are silently ignored (token issued with authorized scopes only)

Endpoint Validation:

• Each endpoint requires specific scopes
• Missing required scopes result in 403 Forbidden with insufficient_scope error
• Error response includes required_scope field indicating needed scope

Example Error Response:

{
  "error": "forbidden",
  "message": "Insufficient permissions",
  "details": {
    "required_scope": "ci:write"
  }
}

Service Account Scopes

Service accounts are configured with specific scopes at creation time. These scopes define what operations the service account can perform.

Creating Service Account with Scopes:

{
  "name": "ci-pipeline-production",
  "scopes": ["ci:write", "artifacts:write"],
  "tenant_id": "tenant_abc123"
}

Updating Service Account Scopes:

{
  "scopes": ["ci:write", "artifacts:write", "admin:read"]
}

Best Practices

1. Principle of Least Privilege: Grant only the minimum scopes required for the operation
2. Separate Accounts: Use different service accounts for different purposes (CI/CD, monitoring, administration)
3. Regular Review: Periodically review and audit scope assignments
4. Scope Rotation: Rotate service account credentials when scopes change significantly
5. Documentation: Document which scopes are required for each integration

Related Documentation

• API Reference - Complete API endpoint documentation
• Authentication - Authentication setup guides
• Error Codes - Error code reference including scope-related errors