Token types
Nayax Core offers two choices under Add Token. Pick App Token for this flow. The app token is a JWT. Lynx Token is an API key, covered on Security & Token. The app token you create is a refresh token. You exchange it for a short-lived access token, and that access token authenticates your Lynx API requests.Scopes
A scope is a permission string that defines what a token can access. Scopes follow the format{domain}:{action} or {domain}:{resource}:{action},
where the domain identifies the area the scope applies to, the optional
resource narrows it to a specific resource within that domain, and the
action identifies the allowed operation.
Common scope examples:
machines:readgrants read access to machine data.orders:*:readgrants read access to all order-related resources.users:app-token:creategrants permission to create app tokens.
Claim types
An app token carries its permissions in one of three claim types, each with its own priority and validation behavior.
For most customer integrations,
appScope is the claim type a Nayax admin
assigns to describe the machines, devices, or orders the integration needs
to access.
Prerequisites
You need a Nayax Core account to create the app token. A Nayax admin must assign its scopes and claim type before you can use it, so requesting a token involves waiting on that approval rather than a fully self-service flow.Create an app token
You create the app token yourself in Nayax Core, but you don’t choose its scopes or claim type. A Nayax admin assigns those separately.1
Create the app token in Nayax Core
From Security & Token,
navigate to the User Tokens section, then click Add Token.
Analytics Platform - Read Only, set an
Expiration Date, then click Generate.2
Wait for a Nayax admin to assign scopes
The admin picks the
appScope, internalScope, or scope claims
described above, based on what the integration needs. You can’t set
these yourself.Exchange the app token
Exchange it for an access token before making requests, using the Lynx API’s endpoint below.Token is the access token itself, a JWT. Use it as a Bearer credential
on subsequent Lynx API requests. For example, retrieving a list of machines:
Security best practices
Follow these practices when requesting and managing app tokens.Storage
Store app tokens in a secure key management system, or as environment variables if you manage your own servers. Encrypt tokens at rest. Never store a token in a plain text file, commit it to version control, or include it in a URL.Scope and expiration
Grant only the scopes an integration needs, and request the shortest expiration that covers its use case, rather than creating tokens casually. Nayax limits each user to 50 tokens, so plan token reuse across integrations that need the same access.Troubleshooting
If a request using an app token, or the access token it produces, fails, check the following common causes.401 Unauthorized
The token is invalid or has expired. Verify the token hasn’t passed its expiration date and that you’re sending it with the correct authorization scheme for the endpoint you’re calling.403 Forbidden
The API returns{"message": "Insufficient permissions to perform this action."}.
The token’s scopes don’t include the resource or action you’re requesting.
Compare the required scope for the endpoint against the appScope,
internalScope, or scope claims on your token, and request a token with
the missing scope if needed.
429 Too Many Requests
You’ve exceeded the rate limit. Cache and reuse access tokens for their full 24-hour lifetime instead of requesting a new one on every call.Next steps
Retrieve machine information
Make your first authenticated call with the access token.
Lynx API reference
Browse the full set of available endpoints.