Skip to main content

Authentication

An unauthenticated user can use only a handful of public mutations and queries. To gain more access, session token needs to be created and used.

Creating API user key​

To generate API user key you can do that at Analytics Hub or after logging into API you can use GraphQL API.

Operation: mutation GenerateUserKey { createUserKey { id secret } }Response Example: { "data": { "createUserKey": { "id": "TjAwN1VzZXJLZXkxMzI", "secret": "2199800d3dabcda4f96a36f0e410ec096aa5f1b59cad10b082cf779edff8541495245300" } } }
How to generate API user key token and secretTry in Explorer
GraphQL
mutation GenerateUserKey {
  createUserKey {
    id
    secret
  }
}

You can also use Lumar CLI to generate API user key.

Obtain session token using API user key and secret token​

Operation: mutation LoginWithUserKey($secret: String!, $userKeyId: ObjectID!) { createSessionUsingUserKey(input: { userKeyId: $userKeyId, secret: $secret }) { token } }Variables: { "userKeyId": 130, "userKeyId": "TjAwN1VzZXJLZXkxMzA", "secret": "Zp8FxbFEri-hU1iE5_9n4890c0TxmCkNIetdz0CvPpEQA-cWg1NErxIMXBnEvRHU1xH1e3qC" }Response Example: { "data": { "createSessionUsingUserKey": { "token": "81372d5bd83919e791be3fe06cdf2b7e760eebe525b3f4f2a8c1a856fc4ea935e14331eb235e7b972d66037e22a4ac7009d9a2d1ff414a751fe29b425c449d00" } } }
How to login using API user key and secret tokenTry in Explorer
GraphQL
mutation LoginWithUserKey($secret: String!, $userKeyId: ObjectID!) {
  createSessionUsingUserKey(input: { userKeyId: $userKeyId, secret: $secret }) {
    token
  }
}

Email and password​

The API does not sign in with an email address and password. The deprecated createSessionUsingUsername mutation fails with USERNAME_PASSWORD_SESSION_REMOVED; integrations that were given time to move keep working until 1 December 2026, after which it fails for every caller. Until then it is limited to 10 calls per minute from one client, after which it returns RATE_LIMIT_EXCEEDED. Create a user key, as above, and call createSessionUsingUserKey with the key's ID and secret instead. The session token it returns is used in exactly the same way.

Using session token​

After signing in you will receive session token that will be valid for 30 days. To authenticate requests to the API send session token in HTTP header x-auth-token value.

curl -H "x-auth-token: <session token>" -XPOST https://api.lumar.io/graphql -H "Content-Type: application/json" --data-raw '{"query": "{version}"}'

Passing invalid session token will result in 401 error.

Password resets​

Changing or resetting a password ends API sessions created without a user key. API user keys and the sessions created from them remain valid, so integrations can continue using their existing tokens. Deleting a user key ends the sessions created from it, including automator tokens issued from those sessions.

Passwords are reset through Lumar sign-in, not through the API. Send users to the "Forgot password?" link on the Lumar sign-in page. For automation, use an API user key with createSessionUsingUserKey (above) or a service account rather than a password.

The two password reset mutations are deprecated and will be removed on 31 January 2027:

  • requestPasswordReset still accepts an email address and always returns true. If the address belongs to a user who signs in with a Lumar password, it sends the Lumar sign-in reset email. The link in that email opens the Lumar sign-in page, where the user chooses the new password; it no longer carries a token for resetPassword.
  • resetPassword no longer resets passwords. Every call fails with PASSWORD_RESET_TOKEN_NOT_SUPPORTED.

Service Accounts​

For programmatic access without user credentials (e.g., CI/CD pipelines, server-to-server communication), you can use Service Accounts. Service accounts authenticate using an API key passed in the x-api-key header:

curl -H "x-api-key: lmr_sa_123_your-secret-key" -XPOST https://api.lumar.io/graphql -H "Content-Type: application/json" --data-raw '{"query": "{version}"}'

See the Service Accounts guide for details on creating and managing service accounts.