API keys

Everything the Arvald dashboard does, it does through a public API. An API key lets your own software do the same: pull your sessions into a spreadsheet, push bookings into your accounting tool, or build something nobody has thought of yet.

You do not need one to use Arvald. If you are not writing software, or paying somebody to, you can skip this page.

Making one

Go to Settings → API keys and choose Create an API key.

Name it after the thing that will use it, not after yourself. In six months "Zapier" tells you what breaks if you revoke it; "Sofia's key" does not.

Then pick what it can do:

• Read only can read your bookings, sessions, clients and payments, and change nothing.
• Full access can do anything you can, including taking payments and issuing refunds.

Start with read only. You can change a key's access later without re-issuing it, and a read-only key that turns out to be enough is a key that can never cause an expensive accident.

The secret is shown once

When the key is created we show you a client ID and a client secret. The secret appears once and we cannot show it again, because we do not keep it in a form anyone can read back, ourselves included.

Copy it somewhere safe before closing that window. A password manager is ideal. If you lose it, there is no recovery: revoke the key, create another, and point your software at the new one.

Treat the secret like a password. Keep it on your server, never in a browser, a phone app, or a public repository.

Using one

A key is not itself a password you send with every request. You exchange it for a short-lived access token, then send that token.

curl -s -X POST https://auth.arvald.com/oauth/v2/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope=openid

That returns an access_token. Send it as a bearer token:

curl https://api.arvald.com/v1/organizations/YOUR_ORG_ID/sessions \
  -H "Authorization: Bearer THE_ACCESS_TOKEN"

The full list of endpoints is in the API reference, which also carries the token URL under its authentication panel.

How long a token lasts

Read expires_in from the token response. It comes back with every token, in seconds, and it is the only answer that is right in every environment:

{ "access_token": "eyJhbGciOi...", "token_type": "Bearer", "expires_in": 3599 }

Keep the token and reuse it until it lapses, then ask for another. Requesting a fresh token for every call works, and it wastes a round trip on every single request.

Do not hardcode a number. The lifetime has already changed once and is not the same on every Arvald environment.

Fetch the next one a little before the old one lapses rather than waiting for a 401. Most HTTP libraries have an OAuth client-credentials helper that handles the whole cycle for you, and using one is the easiest way to get this right.

If you are testing against the development environment, the token URL is https://auth.arvald.dev/oauth/v2/token. The two are separate systems: a key from one is not recognised by the other, and mixing them up gives you an invalid_client error that looks like a bad secret.

Test keys and live keys are different keys

A key is tied to the mode it was created in, permanently.

Create a key while the dashboard is in test mode and it reaches only your test data. It cannot touch a real booking or a real card, whatever it asks for. Create one in live mode and it reaches your real business.

This is not a setting you can flip afterwards, and that is the point: a key you have been experimenting with can never quietly become one that moves real money. Build against a test key, and issue a separate live key when you are ready.

If a live-mode request comes back complaining about the mode, you are using a test key. Make a live one rather than trying to talk it round.

Revoking

Revoke a key the moment it is no longer needed, or if you think the secret has been seen by anyone it should not have been.

Revoking takes effect immediately, on the very next request. That is worth being precise about, because a token this key has already handed out stays valid until it expires on its own: it is the key being revoked that stops it, not the token lapsing. So revoking really does end the problem, right away, which is the point. There is no way to un-revoke.

Replacing a key without downtime: create the new one first, move your software across, check it works, and only then revoke the old one. A key's secret cannot be rotated in place, so this is the only way to swap one without a gap.

Things worth knowing

A key acts for your brand, not for you. It is not tied to your login. It keeps working if you change your password, and it does not stop when you sign out.

A key cannot manage keys. Even a full-access key cannot create or revoke keys, including itself. That is deliberate: if a secret ever leaks, revoking it has to actually end the problem, rather than becoming a race against something minting replacements.

A key cannot see another brand. If you run more than one, each needs its own.

"Last used" is approximate. We refresh it at most once an hour, so a key in constant use can show a time up to an hour old. It is there to help you spot a key nobody uses, not to watch traffic live.

You can have up to 10 keys per brand, per mode. Revoked keys do not count.