Service Accounts

Service Accounts provide a way to grant programmatic access to the Lumar API without requiring user credentials. They are ideal for automated pipelines, CI/CD integrations, and server-to-server communication.

Overview

Service accounts are associated with a Lumar account and have a configurable role that determines their access permissions. Each service account can have multiple API keys, which are used for authentication.

Key Concepts

Service Account: An identity for programmatic API access, associated with a specific Lumar account
Service Account Key: An API key used to authenticate as a service account. Keys can be named, have expiration dates, and can be revoked
Role: Determines what operations the service account can perform (e.g., Admin, Editor, Viewer)

API Key Format

Service account API keys follow this format:

lmr_sa_{serviceAccountId}_{secret}

The full key is only visible once when created. Store it securely as it cannot be retrieved later.

Authentication

To authenticate using a service account, include the API key in the x-api-key header:

curl -H "x-api-key: lmr_sa_123_your-secret-key" \
  -X POST https://api.lumar.io/graphql \
  -H "Content-Type: application/json" \
  --data-raw '{"query": "{ node(id: \"TjAwN0FjY291bnQ3MTU\") { ... on Account { id name } } }"}'

The service account will have access to resources based on its assigned role within the associated account.

Prerequisites

You must have Admin role access to the Lumar account
Service accounts can only be managed by authenticated users (not other service accounts)

Creating a Service Account

Use the createServiceAccount mutation to create a new service account.

Operation: mutation CreateServiceAccount($input: CreateServiceAccountInput!) { createServiceAccount(input: $input) { serviceAccount { id name description roleCode enabled createdAt } } }Variables: { "input": { "accountId": "TjAwN0FjY291bnQ3MTU", "name": "CI/CD Pipeline", "description": "Service account for automated deployments", "roleCode": "Editor" } }Response Example: { "data": { "createServiceAccount": { "serviceAccount": { "id": "TjAzNlNlcnZpY2VBY2NvdW50MQ", "name": "CI/CD Pipeline", "description": "Service account for automated deployments", "roleCode": "Editor", "enabled": true, "createdAt": "2024-12-23T10:00:00.000Z" } } } }

CreateServiceAccountTry in Explorer

GraphQL

mutation CreateServiceAccount($input: CreateServiceAccountInput!) {
  createServiceAccount(input: $input) {
    serviceAccount {
      id
      name
      description
      roleCode
      enabled
      createdAt
    }
  }
}

Input Fields

Field	Type	Required	Description
`accountId`	ObjectID	Yes	The ID of the account to create the service account in
`name`	String	Yes	A name for the service account (max 255 characters)
`description`	String	No	A description of the service account's purpose
`roleCode`	RoleCode	Yes	The role to assign (`Admin`, `Editor`, or `Viewer`)

Listing Service Accounts

Query the serviceAccounts field on an Account to list all service accounts.

Operation: query GetServiceAccounts($accountId: ObjectID!) { node(id: $accountId) { ... on Account { id name serviceAccounts { id name description roleCode enabled createdAt updatedAt keys { id name lastUsedAt expiresAt revokedAt createdAt } } } } }Variables: { "accountId": "TjAwN0FjY291bnQ3MTU" }Response Example: { "data": { "node": { "id": "TjAwN0FjY291bnQ3MTU", "name": "My Account", "serviceAccounts": [ { "id": "TjAzNlNlcnZpY2VBY2NvdW50MQ", "name": "CI/CD Pipeline", "description": "Service account for automated deployments", "roleCode": "Editor", "enabled": true, "createdAt": "2024-12-23T10:00:00.000Z", "updatedAt": "2024-12-23T10:00:00.000Z", "keys": [ { "id": "TjAzN1NlcnZpY2VBY2NvdW50S2V5MQ", "name": "Production Key", "lastUsedAt": "2024-12-23T15:30:00.000Z", "expiresAt": "2025-12-31T23:59:59.000Z", "revokedAt": null, "createdAt": "2024-12-23T10:00:00.000Z" } ] } ] } } }

GetServiceAccountsTry in Explorer

GraphQL

query GetServiceAccounts($accountId: ObjectID!) {
  node(id: $accountId) {
    ... on Account {
      id
      name
      serviceAccounts {
        id
        name
        description
        roleCode
        enabled
        createdAt
        updatedAt
        keys {
          id
          name
          lastUsedAt
          expiresAt
          revokedAt
          createdAt
        }
      }
    }
  }
}

Retrieving a Service Account

Use the serviceAccount query to get a specific service account by ID.

Operation: query GetServiceAccount($serviceAccountId: ObjectID!) { serviceAccount(id: $serviceAccountId) { id name description roleCode enabled createdAt updatedAt account { id name } createdByUser { id username } role { code name } keys { id name lastUsedAt expiresAt revokedAt createdAt } } }Variables: { "serviceAccountId": "TjAzNlNlcnZpY2VBY2NvdW50MQ" }Response Example: { "data": { "serviceAccount": { "id": "TjAzNlNlcnZpY2VBY2NvdW50MQ", "name": "CI/CD Pipeline", "description": "Service account for automated deployments", "roleCode": "Editor", "enabled": true, "createdAt": "2024-12-23T10:00:00.000Z", "updatedAt": "2024-12-23T10:00:00.000Z", "account": { "id": "TjAwN0FjY291bnQ3MTU", "name": "My Account" }, "createdByUser": { "id": "TjAwOFVzZXIxMjM", "username": "admin@example.com" }, "role": { "code": "Editor", "name": "Editor" }, "keys": [ { "id": "TjAzN1NlcnZpY2VBY2NvdW50S2V5MQ", "name": "Production Key", "lastUsedAt": "2024-12-23T15:30:00.000Z", "expiresAt": "2025-12-31T23:59:59.000Z", "revokedAt": null, "createdAt": "2024-12-23T10:00:00.000Z" } ] } } }

GetServiceAccountTry in Explorer

GraphQL

query GetServiceAccount($serviceAccountId: ObjectID!) {
  serviceAccount(id: $serviceAccountId) {
    id
    name
    description
    roleCode
    enabled
    createdAt
    updatedAt
    account {
      id
      name
    }
    createdByUser {
      id
      username
    }
    role {
      code
      name
    }
    keys {
      id
      name
      lastUsedAt
      expiresAt
      revokedAt
      createdAt
    }
  }
}

Updating a Service Account

Use the updateServiceAccount mutation to modify a service account's properties.

Operation: mutation UpdateServiceAccount($input: UpdateServiceAccountInput!) { updateServiceAccount(input: $input) { serviceAccount { id name description roleCode enabled updatedAt } } }Variables: { "input": { "id": "TjAzNlNlcnZpY2VBY2NvdW50MQ", "name": "Production CI/CD Pipeline", "enabled": true } }Response Example: { "data": { "updateServiceAccount": { "serviceAccount": { "id": "TjAzNlNlcnZpY2VBY2NvdW50MQ", "name": "Production CI/CD Pipeline", "description": "Service account for automated deployments", "roleCode": "Editor", "enabled": true, "updatedAt": "2024-12-23T11:00:00.000Z" } } } }

UpdateServiceAccountTry in Explorer

GraphQL

mutation UpdateServiceAccount($input: UpdateServiceAccountInput!) {
  updateServiceAccount(input: $input) {
    serviceAccount {
      id
      name
      description
      roleCode
      enabled
      updatedAt
    }
  }
}

Updatable Fields

Field	Type	Description
`name`	String	Update the service account name
`description`	String	Update or clear the description
`roleCode`	RoleCode	Change the assigned role
`enabled`	Boolean	Enable or disable the service account

Deleting a Service Account

Use the deleteServiceAccount mutation to remove a service account. This will also invalidate all associated API keys.

Operation: mutation DeleteServiceAccount($input: DeleteServiceAccountInput!) { deleteServiceAccount(input: $input) { serviceAccount { id } } }Variables: { "input": { "id": "TjAzNlNlcnZpY2VBY2NvdW50MQ" } }Response Example: { "data": { "deleteServiceAccount": { "serviceAccount": { "id": "TjAzNlNlcnZpY2VBY2NvdW50MQ" } } } }

DeleteServiceAccountTry in Explorer

GraphQL

mutation DeleteServiceAccount($input: DeleteServiceAccountInput!) {
  deleteServiceAccount(input: $input) {
    serviceAccount {
      id
    }
  }
}

Managing API Keys

Creating an API Key

Use the createServiceAccountKey mutation to generate a new API key. Important: The secret field must be requested and will only be returned once.

Operation: mutation CreateServiceAccountKey($input: CreateServiceAccountKeyInput!) { createServiceAccountKey(input: $input) { id name secret expiresAt createdAt } }Variables: { "input": { "serviceAccountId": "TjAzNlNlcnZpY2VBY2NvdW50MQ", "name": "Production Key", "expiresAt": "2025-12-31T23:59:59.000Z" } }Response Example: { "data": { "createServiceAccountKey": { "id": "TjAzN1NlcnZpY2VBY2NvdW50S2V5MQ", "name": "Production Key", "secret": "lmr_sa_1_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0", "expiresAt": "2025-12-31T23:59:59.000Z", "createdAt": "2024-12-23T10:00:00.000Z" } } }

CreateServiceAccountKeyTry in Explorer

GraphQL

mutation CreateServiceAccountKey($input: CreateServiceAccountKeyInput!) {
  createServiceAccountKey(input: $input) {
    id
    name
    secret
    expiresAt
    createdAt
  }
}

Input Fields

Field	Type	Required	Description
`serviceAccountId`	ObjectID	Yes	The ID of the service account
`name`	String	No	A name to identify this key
`expiresAt`	DateTime	No	Optional expiration date for the key

Listing API Keys

API keys are accessible via the keys field on a ServiceAccount:

Operation: query GetServiceAccountKeys($serviceAccountId: ObjectID!) { serviceAccount(id: $serviceAccountId) { id name keys { id name lastUsedAt expiresAt revokedAt createdAt createdByUser { id username } } } }Variables: { "serviceAccountId": "TjAzNlNlcnZpY2VBY2NvdW50MQ" }Response Example: { "data": { "serviceAccount": { "id": "TjAzNlNlcnZpY2VBY2NvdW50MQ", "name": "CI/CD Pipeline", "keys": [ { "id": "TjAzN1NlcnZpY2VBY2NvdW50S2V5MQ", "name": "Production Key", "lastUsedAt": "2024-12-23T15:30:00.000Z", "expiresAt": "2025-12-31T23:59:59.000Z", "revokedAt": null, "createdAt": "2024-12-23T10:00:00.000Z", "createdByUser": { "id": "TjAwOFVzZXIxMjM", "username": "admin@example.com" } }, { "id": "TjAzN1NlcnZpY2VBY2NvdW50S2V5Mg", "name": "Staging Key", "lastUsedAt": null, "expiresAt": null, "revokedAt": "2024-12-20T10:00:00.000Z", "createdAt": "2024-12-01T10:00:00.000Z", "createdByUser": { "id": "TjAwOFVzZXIxMjM", "username": "admin@example.com" } } ] } } }

GetServiceAccountKeysTry in Explorer

GraphQL

query GetServiceAccountKeys($serviceAccountId: ObjectID!) {
  serviceAccount(id: $serviceAccountId) {
    id
    name
    keys {
      id
      name
      lastUsedAt
      expiresAt
      revokedAt
      createdAt
      createdByUser {
        id
        username
      }
    }
  }
}

Note: The secret field is only returned when creating a key. For existing keys, only metadata (name, creation date, last used, expiration, revocation status) is available.

Revoking an API Key

Use the revokeServiceAccountKey mutation to revoke an API key. Revoked keys cannot be used for authentication.

Operation: mutation RevokeServiceAccountKey($input: RevokeServiceAccountKeyInput!) { revokeServiceAccountKey(input: $input) { serviceAccountKey { id revokedAt } } }Variables: { "input": { "id": "TjAzN1NlcnZpY2VBY2NvdW50S2V5MQ" } }Response Example: { "data": { "revokeServiceAccountKey": { "serviceAccountKey": { "id": "TjAzN1NlcnZpY2VBY2NvdW50S2V5MQ", "revokedAt": "2024-12-23T12:00:00.000Z" } } } }

RevokeServiceAccountKeyTry in Explorer

GraphQL

mutation RevokeServiceAccountKey($input: RevokeServiceAccountKeyInput!) {
  revokeServiceAccountKey(input: $input) {
    serviceAccountKey {
      id
      revokedAt
    }
  }
}

Best Practices

Use descriptive names: Give service accounts and keys meaningful names that indicate their purpose
Set expiration dates: Use expiring keys for temporary access or rotate keys regularly
Use minimal permissions: Assign the lowest role that meets your needs
Secure storage: Store API keys securely (e.g., in environment variables or secret managers)
Monitor usage: Check the lastUsedAt field to track key usage
Revoke unused keys: Remove keys that are no longer needed
One key per integration: Create separate keys for different integrations to simplify revocation

Access Control

Service accounts inherit permissions based on their assigned role:

Role	Description
`Admin`	Full access to all account resources
`Editor`	Can create and modify projects and crawls
`Viewer`	Read-only access to account resources

Service accounts cannot:

Create or manage other service accounts
Create or manage service account keys
Perform user-specific operations (e.g., managing user settings)

Error Handling

Common errors when working with service accounts:

Error	Description
`Unauthorized`	You don't have Admin access to the account
`ServiceAccount not found`	The specified service account doesn't exist or you don't have access
`The 'secret' field must be requested...`	When creating a key, you must request the `secret` field in the response

Overview​

Key Concepts​

API Key Format​

Authentication​

Prerequisites​

Creating a Service Account​

Input Fields​

Listing Service Accounts​

Retrieving a Service Account​

Updating a Service Account​

Updatable Fields​

Deleting a Service Account​

Managing API Keys​

Creating an API Key​

Input Fields​

Listing API Keys​

Revoking an API Key​

Best Practices​

Access Control​

Error Handling​

Overview

Key Concepts

API Key Format

Authentication

Prerequisites

Creating a Service Account

Input Fields

Listing Service Accounts

Retrieving a Service Account

Updating a Service Account

Updatable Fields

Deleting a Service Account

Managing API Keys

Creating an API Key

Input Fields

Listing API Keys

Revoking an API Key

Best Practices

Access Control

Error Handling