Skip to content

Access Control Guide

Overview

Centrali uses OAuth 2.0 and OIDC for authentication and authorization. Access control is workspace-scoped with role-based permissions.

Authentication Methods

User Authentication (OAuth 2.0)

For console UI and user-facing applications.

Service Account Authentication

For API access and automation. See the Service Account Authentication Guide for complete details.

Workspace Roles

Owner

  • Full workspace access
  • Manage users and service accounts
  • Billing and usage management
  • Delete workspace

Admin

  • Manage structures, records, functions
  • Invite users
  • Configure webhooks and triggers
  • View usage

Developer

  • Create and modify structures
  • Manage records
  • Write and deploy functions
  • View logs

Viewer

  • Read-only access to all workspace data
  • Cannot create or modify resources

Service Account Permissions

Fine-grained permissions for API access:

Data Permissions: - read:structures - View structure definitions - write:structures - Create/modify structures - read:records - Query records - write:records - Create/update/delete records

Function Permissions: - read:functions - View functions - write:functions - Create/modify functions - execute:functions - Invoke functions

Storage Permissions: - read:storage - Download files - write:storage - Upload/delete files

Creating Service Accounts

curl -X POST https://api.centrali.io/workspace/my-workspace/api/v1/service-accounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "permissions": [
      "read:records",
      "write:records",
      "read:structures"
    ]
  }'

Response includes client credentials: 

{
  "id": "sa_abc123",
  "clientId": "centrali_client_xyz",
  "clientSecret": "secret_abc123...",
  "permissions": ["read:records", "write:records", "read:structures"]
}

OAuth 2.0 Token Exchange

Exchange client credentials for access token:

curl -X POST https://auth.centrali.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=centrali_client_xyz" \
  -d "client_secret=secret_abc123..." \
  -d "scope=workspace:my-workspace"

Response: 

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using Access Tokens

Include token in API requests:

curl -X GET https://api.centrali.io/workspace/my-workspace/api/v1/structures \
  -H "Authorization: Bearer eyJhbGc..."

Best Practices

Security

  • Rotate service account credentials regularly
  • Use minimum required permissions
  • Never commit credentials to version control
  • Use environment variables for secrets
  • Monitor API access logs

Service Accounts

  • Create separate service accounts per application
  • Use descriptive names (e.g., "Production API", "Staging Worker")
  • Document what each service account is used for
  • Revoke unused service accounts

Token Management

  • Cache tokens until expiration
  • Implement automatic token refresh
  • Handle 401 errors with re-authentication
  • Use short-lived tokens in production

Revoking Access

Delete Service Account

curl -X DELETE https://api.centrali.io/workspace/my-workspace/api/v1/service-accounts/sa_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Rotate Credentials

curl -X POST https://api.centrali.io/workspace/my-workspace/api/v1/service-accounts/sa_abc123/rotate \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns new client secret.