The API token for the BrynQ Agent

The API token for the BrynQ Agent

What is the Agent token?

The BrynQ Agent needs one key to work: a BrynQ API token that belongs to your BrynQ environment. You paste it once while you install the Agent. The Agent keeps it on the server and uses it to prove to BrynQ which customer it belongs to.

Without a valid token, the Agent cannot set up its secure connection to BrynQ and cannot update itself.

What the token is used for

WhenWhat the token does
During installationBrynQ checks the token and looks up the customer it belongs to. It then creates the secure connection and your Agent's own address: https://<your-customer>.brynq-agent.com.
Automatic updatesThe Agent uses the token to check for new versions and to download them from BrynQ.
Connection testThe BrynQ connection page of the local admin dashboard uses the token to test whether BrynQ accepts this Agent.
Incoming requestsThe Agent only accepts requests for your customer. Requests that name another customer are refused, even with a valid token.
ℹ️ Good to know: the token is not the password of your local system (SQL Server, Active Directory, Sage). Those settings are entered separately in the installer or on the admin dashboard.

Which token you need

The Agent accepts only a token that is linked to exactly one customer: the customer the Agent is installed for.

  • ✅ A token created in your own BrynQ environment.
  • ❌ A personal token or administrator token that has access to several customers, or to none. BrynQ refuses it and the installer shows that it is not an agent token.
  • ❌ API credentials with a Client ID and Client Secret. The Agent needs a single token, not a Client ID and secret.

How to get the token

Ask your BrynQ consultant or BrynQ support for the Agent token of your environment. BrynQ creates it for you and sends it securely.

Things to agree on before the token is created:

  • Validity period. A token can be valid for 30, 90, 180 or 365 days, or have no expiry date. When the token expires, the Agent can no longer update itself or set up its connection again. Agree who replaces the token in time.
  • IP whitelist (optional). The token can be limited to certain IP addresses. If you want this, give BrynQ the public IP address your server uses to reach the internet. The installer and the admin dashboard show this address. Leave the whitelist empty if your server has no fixed public address.
⚠️ Keep the token secret. BrynQ shows a token only once, when it is created. Treat it like a password: don't share it in chat or email threads with people who don't need it, and don't store it in a shared document.

For BrynQ consultants

  1. Open the customer's environment in BrynQ.
  2. In the sidebar, under Developer, click API Credentials.
  3. Open the Legacy tokens tab (marked v2).
    The Legacy tokens (v2) tab on the API Credentials page
  4. Click Create legacy token. Enter a clear Label, for example BrynQ Agent – <server name>, choose the Validity period and, if agreed, add the server's public IP address under Allowed IP addresses (press Enter after each address). Then click Create legacy token in the dialog.
    The Create legacy token dialog
  5. Copy the token right away and click I have saved my token.
Roadmap: the Agent uses a legacy token (v2) for now. In the future it will use API credentials (v1) instead. This article will be updated when that changes.

Don't use a token from the Admin Portal › API access page: those are administrator tokens for all customers, and the Agent refuses them.

Enter the token during installation

  1. Start the BrynQ Agent installer (see Install the BrynQ Agent for the full installation).
  2. On the Cloud connection page, paste the token in the API token field. The field is masked.
  3. The installer checks the token with BrynQ while you type. Next becomes available only once BrynQ accepts it. The customer is filled in automatically from the token.
  4. Finish the installation. The Agent stores the token on the server, protected with Windows encryption (DPAPI). It is never written to logs or shown again.

When you reinstall or upgrade, the installer notices that a token is already stored. Keep Keep the existing API token (recommended) selected, or choose Replace it with a new API token and paste the new one.

Replace an expired or revoked token

You don't need to reinstall the Agent to replace the token.

  1. Ask BrynQ for a new Agent token.
  2. Open the local admin dashboard on the Agent server.
  3. Go to the BrynQ connection page.
  4. Under Replace API token, paste the token in New API token and click Check and save.

BrynQ checks the new token first. It is saved only when BrynQ accepts it for your customer, so a wrong token never replaces a working one.

Troubleshooting

The installer and the BrynQ connection page tell you why BrynQ does not accept a token. For other problems, see Troubleshooting the BrynQ Agent.

MessageWhat it meansWhat to do
BrynQ does not know this API token (TOKEN_NOT_FOUND)The token does not exist, was revoked, or was not copied completely.Copy the whole token again. Still refused? Ask BrynQ for a new token.
The API token has expired (TOKEN_EXPIRED)The validity period of the token has passed.Ask BrynQ for a new token and replace it on the BrynQ connection page.
The BrynQ user this API token belongs to no longer exists (RELATED_USER_NOT_FOUND)The token was created by a BrynQ user who has since been removed.Ask BrynQ for a new token.
BrynQ only accepts this API token from other IP addresses (IP_NOT_ALLOWED)The token has an IP whitelist that does not include your server's public IP address.Ask BrynQ to add the address shown under Public IP address to the token's whitelist, or to remove the whitelist. Then click Check again.
BrynQ knows the token, but it is not an agent token (AGENT_TOKEN_MUST_TARGET_EXACTLY_ONE_CUSTOMER)The token is linked to several customers or to none, for example an administrator token.Use a token created in your own BrynQ environment (see Which token you need).
BrynQ links the token to another customerThe token belongs to a different BrynQ environment than this Agent.Use the Agent token of your own environment.
The BrynQ platform does not respondBrynQ is temporarily busy or unavailable.Wait a few minutes and click Check again.
BrynQ cannot be reachedThe server cannot make an outgoing HTTPS connection to BrynQ.Ask your IT administrator to allow outgoing HTTPS traffic to BrynQ (see below), including through any proxy.

BrynQ's address for your firewall

The token check, the connection test and the updates all go outward from your server to BrynQ. No inbound port is needed. If your firewall or proxy only allows outgoing traffic to approved destinations, allow:

DestinationIP addressPort
app.brynq.com20.54.225.251TCP 443 (HTTPS)

Allow the host name app.brynq.com where your firewall supports it, and the IP address where it only accepts IP addresses. The Outbound connections check on the Troubleshooting page of the admin dashboard shows whether the server can reach BrynQ. The Cloudflare Tunnel needs its own outgoing port: see Network settings of the BrynQ Agent.

Don't confuse the two addresses: 20.54.225.251 is BrynQ's address, which your firewall allows. The Public IP address of your server is what BrynQ adds to the token's IP whitelist.