Machine tokens

Machine tokens are JWTs used to authenticate machine requests your application makes.

They are similiar to session tokens however, unlike session tokens, machine tokens are not associated with a user. Instead you are responsible for determining the identity of the machine making the request.

Creating machine tokens

Machine ID

Every machine token you create needs to be associated with a machine_id. You can pick any value for the machine_id as long as it meets the following requirements:

• It must be prefixed with mch_
• It must only contain lowercase letters and numbers
• It must be 96 characters or less

• Examples:
  • ✅ mch_cron_service
  • ✅ mch_background_worker
  • ✅ mch_device_6580fc77_afca_47ac_8973_b7261d14e4c7
  • ❌ user_2p94zsO6sBvVZR5Ca0KfBNLM36Z
  • ❌ mch-invalid
  • ❌ MCH_UPPERCASE

Claims

You can add custom claims to your machine token to include any additional information that your application might need. Claims are key-value pairs included in the token's payload, and they can convey important data such as permissions, roles, or any other attributes relevant to the machine's identity.

For example, it is a good practice to include any permissions that your service requires directly in the claims. This allows your backend to easily verify what actions the machine is authorized to perform.

Expires In Seconds

The expiresInSeconds parameter defines how long the machine token remains valid, specified in seconds. This parameter is optional and defaults to 60 seconds (1 minute).

If you need the machine token to be valid for a longer period of time, you can set the expiresInSeconds parameter to a higher value. However, because machine tokens are JWTs, longer-lived tokens can present a higher security risk if compromised, while shorter-lived tokens may require more frequent token generation, potentially impacting your Backend API rate limits. Therefore, it's important to balance token lifespan with security requirements and rate limit considerations.

Clock Skew

The allowedClockSkew parameter provides a leeway in seconds to account for clock differences between servers. This setting affects the nbf (Not Before) claim in the token, calculated as nbf = current_time - allowed_clock_skew. The default value is 5 seconds.

Adjusting the clock skew helps prevent token validation failures due to minor time discrepancies between the issuing server and the verifying server.

Default machine claims

Every generated token has default claims that cannot be overridden by custom claims. Clerk's default claims include:

• exp: expiration time - the time after which the token will expire, as a Unix timestamp. Determined using the Token Expires In Seconds request body parameter when creating machine tokens. See RFC 7519⁠ for more information.
• iat: issued at - the time at which the token was issued as a Unix timestamp. For example: 1516239022. See RFC 7519⁠ for more information.
• jti: JWT ID - the ID of the token internally generated by Clerk. For example: a1b2c3d4e5f67890abcd. See RFC 7519⁠ for more information.
• iss: issuer - the Frontend API URL of your instance. For example: https://clerk.your-site.com for a production instance or https://your-site.clerk.accounts.dev for a development instance. See RFC 7519⁠ for more information.
• nbf: not before - the time before which the token is considered invalid, as a Unix timestamp. Determined using the Allowed Clock Skew request body parameter when creating machine tokens. See RFC 7519⁠ for more information.
• sub: subject - the ID of the machine that created the token. Determined using the Machine ID request body parameter when creating machine tokens. For example: mch_123. See RFC 7519⁠ for more information.

Using Machine Tokens to create and verify requests

To start using machine tokens to create and verify requests, refer to making machine requests.