Skip to main content

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.

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

Try in explorer

Input Fields​

FieldTypeRequiredDescription
accountIdObjectIDYesThe ID of the account to create the service account in
nameStringYesA name for the service account (max 255 characters)
descriptionStringNoA description of the service account's purpose
roleCodeRoleCodeYesThe role to assign (Admin, Editor, or Viewer)

Listing Service Accounts​

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

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
        }
      }
    }
  }
}

Try in explorer

Retrieving a Service Account​

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

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

Try in explorer

Updating a Service Account​

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

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

Try in explorer

Updatable Fields​

FieldTypeDescription
nameStringUpdate the service account name
descriptionStringUpdate or clear the description
roleCodeRoleCodeChange the assigned role
enabledBooleanEnable 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.

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

Try in explorer

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.

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

Try in explorer

Input Fields​

FieldTypeRequiredDescription
serviceAccountIdObjectIDYesThe ID of the service account
nameStringNoA name to identify this key
expiresAtDateTimeNoOptional expiration date for the key

Listing API Keys​

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

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

Try in explorer

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.

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

Try in explorer

Best Practices​

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

Access Control​

Service accounts inherit permissions based on their assigned role:

RoleDescription
AdminFull access to all account resources
EditorCan create and modify projects and crawls
ViewerRead-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:

ErrorDescription
UnauthorizedYou don't have Admin access to the account
ServiceAccount not foundThe 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