Skip to main content

API Tokens

API tokens enable programmatic access to Openlane systems and are critical for secure system integration and automation. They provide a mechanism for authenticating machine-to-machine communications and service integrations.

What Are API Tokens?​

API tokens are authentication credentials that allow external systems, applications, and services to programmatically access Openlane APIs. They serve as a secure alternative to user credentials for automated processes, system integrations, and service-to-service communications.

Compliance Significance​

API tokens are essential for:

  • Access Control: Implementing fine-grained access permissions for automated systems
  • Audit Trail: Tracking programmatic access to compliance-sensitive data
  • Security Compliance: Meeting requirements for secure API authentication (SOC 2, ISO 27001)
  • Segregation of Duties: Separating automated access from human user access
  • Incident Response: Quickly identifying and revoking compromised automated access

API Token Types​

Organization-Level API Tokens​

  • Scope: Organization-wide access with configurable permissions
  • Prefix: tola_ (Token Openlane API)
  • Use Case: System integrations, organizational automation
  • Lifecycle: Managed by organization administrators

Personal Access Tokens​

  • Scope: User-specific access with inherited permissions
  • Prefix: tolp_ (Token Openlane Personal)
  • Use Case: User-specific automation, personal tooling
  • Lifecycle: Managed by individual users

Properties​

Core Information​

  • ID: Unique identifier for the token
  • Name: Human-readable token name for identification
  • Token: Cryptographically secure token value (write-only)
  • Description: Purpose and usage description
  • Owner: Organization or user that owns the token

Access Control​

  • Scopes: Array of permission scopes (read, write, admin)
  • Active Status: Boolean indicating if token is active
  • SSO Authorizations: Organization-specific SSO verification timestamps

Lifecycle Management​

  • Created At: Token creation timestamp
  • Expires At: Optional expiration date
  • Last Used At: Timestamp of most recent usage
  • Revoked At: Revocation timestamp (if applicable)
  • Revoked By: User who revoked the token
  • Revoked Reason: Reason for token revocation

GraphQL Operations​

Query API Tokens​

query GetAPITokens($first: Int, $where: APITokenWhereInput) {
  apiTokens(first: $first, where: $where) {
    edges {
      node {
        id
        name
        description
        scopes
        isActive
        expiresAt
        lastUsedAt
        createdAt
        revokedReason
        revokedBy
        owner {
          id
          name
        }
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

Create API Token​

mutation CreateAPIToken($input: CreateAPITokenInput!) {
  createAPIToken(input: $input) {
    apiToken {
      id
      name
      token
      description
      scopes
      expiresAt
      isActive
      createdAt
    }
  }
}

Update API Token (Revoke)​

mutation UpdateAPIToken($id: ID!, $input: UpdateAPITokenInput!) {
  updateAPIToken(id: $id, input: $input) {
    apiToken {
      id
      name
      isActive
      revokedReason
      revokedBy
      updatedAt
    }
  }
}

Delete API Token​

mutation DeleteAPIToken($id: ID!) {
  deleteAPIToken(id: $id) {
    deletedID
  }
}

API Access​

Security and Compliance Considerations​

Access Control​

  • Role-Based Permissions: Tokens inherit permissions from their owner's roles
  • Scope Limitation: Restrict token permissions to minimum required access
  • Organization Boundaries: Tokens cannot access resources outside their organization
  • SSO Integration: Supports organization-level SSO authorization requirements

Audit and Monitoring​

  • Usage Tracking: All API token usage is logged for audit purposes
  • Access Patterns: Monitor for unusual access patterns or suspicious activity
  • Revocation Audit: Complete audit trail for token lifecycle events
  • Compliance Reporting: Generate reports on token usage for compliance reviews

Security Best Practices​

  • Token Rotation: Implement regular token rotation schedules
  • Expiration Policies: Set appropriate expiration dates for all tokens
  • Secure Storage: Store tokens securely and never expose in logs
  • Least Privilege: Grant minimum necessary permissions
  • Regular Review: Periodically review and audit active tokens

Common Use Cases​

CI/CD Pipeline Integration​

# GitHub Actions example using GraphQL
env:
  OPENLANE_API_TOKEN: ${{ secrets.OPENLANE_API_TOKEN }}

steps:
  - name: Deploy compliance artifacts
    run: |
      # Use GraphQL to create evidence records
      curl -X POST "https://api.openlane.io/query" \
        -H "Authorization: Bearer $OPENLANE_API_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"query": "mutation { createEvidence(input: {...}) { evidence { id } } }"}'

Automated Compliance Monitoring​

Monitor control implementation status through GraphQL queries using authenticated API requests to retrieve control information including ID, name, and status.

Security Scanning Integration​

Automated vulnerability scan results can be uploaded via GraphQL mutations using the createScan mutation with scan type and results data.

Relationships​

API tokens integrate with several other Openlane objects:

Direct Relationships​

  • Organization: Organizational API tokens belong to organizations
  • User: Personal access tokens belong to individual users
  • Events: All token operations generate audit events

Indirect Relationships​

  • Controls: API tokens can be used to automate control evidence collection
  • Evidence: Tokens enable automated evidence upload and management
  • Risks: API tokens can trigger risk assessments based on automated findings
  • Tasks: Tokens can create and update compliance tasks programmatically