Back to Developers & API

How do I create API keys and use OAuth2?

Generate scoped API keys (shown once, hashed at rest), edit, rotate or revoke them; or register an OAuth2 client to exchange a client id + secret for short-lived access tokens with refresh.

~4 min read · For admin · Updated 4 Aug 2026

Quick answer

Create scoped API keys in Admin → Settings → Developer & API — they're shown once and hashed at rest, and you can edit their permissions, rotate the secret, or revoke them. For apps that prefer short-lived tokens, register an OAuth2 client and exchange its id + secret at /api/oauth/token.

API keys

  1. Create

    Name it, pick test/live, tick the scopes, generate. Copy the dmk_test_… / dmk_live_… value — it's the only time it's shown.

  2. Edit

    Change the name or scopes any time from the key's row.

  3. Rotate

    Generates a new secret and immediately invalidates the old one — update your integration with the new value.

  4. Revoke

    Stops the key working at once; the row is kept for your audit trail.

OAuth2 (client-credentials + refresh)

Register a client in the console (scopes limited to your enabled modules); the client secret is shown once. Then:

# Get a short-lived access token
curl -s https://ashr.work/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"dmk_client_…","client_secret":"dmk_secret_…"}'
# → { "access_token":"dmk_at_…", "token_type":"Bearer", "expires_in":3600,
#     "refresh_token":"dmk_rt_…", "scope":"leave:read leave:write" }

# When it expires, rotate with the refresh token
curl -s https://ashr.work/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"refresh_token","refresh_token":"dmk_rt_…"}'

Send the dmk_at_… token exactly like a key: Authorization: Bearer dmk_at_…. A token can never exceed its client's scopes, and refreshing rotates the tokens (the old pair is revoked).

Frequently asked questions

What's the difference between a key and OAuth?
An API key is a long-lived secret you send directly — simplest for scripts. OAuth2 client-credentials suits apps that prefer short-lived tokens — you exchange a client id + secret for an access token that expires, with a refresh token to get the next one. Both carry the same scopes.
I lost a key — can I recover it?
No. Keys and secrets are hashed at rest and only shown once. Rotate the key (new secret, old one dies immediately) or create a new one.
Can I limit what a key can do?
Yes — pick only the module permissions you need when creating it, and edit them later. Scopes are limited to your enabled modules.

Related articles