#API Keys

API keys are how anything that isn't a browser talks to monetr. A key has two halves: an ID that looks like any other monetr identifier, and a secret that's shown to you exactly once. Together they go over HTTP Basic auth, which is covered in the overview.

They're documented here anyway so you know the shape of what the app is doing, and so the list of what exists is complete.

#The API key object

The secret is never in this object. monetr stores a public key derived from the secret and verifies against that, so it genuinely cannot give the secret back to you, even in principle.

#GET List API keys

Returns every key on your account, including revoked ones.

In the app: The API keys table under settings.

GET /api/keys

Auth: Not available to API keys.

#Response

An array of API key objects.

[
  {
    "apiKeyId": "key_01hy4rfqk8z4xv1c2v44cf6abc",
    "name": "Budget sync script",
    "createdAt": "2024-06-11T20:14:03.882Z",
    "createdBy": "user_01fpwx3sdm7kb1s0jbrbvbdw4c",
    "updatedAt": "2024-06-11T20:14:03.882Z"
  },
  {
    "apiKeyId": "key_01hz8p2mvw6te4rk9jnxdb5cgh",
    "name": "Old laptop",
    "createdAt": "2024-02-03T11:47:19.220Z",
    "createdBy": "user_01fpwx3sdm7kb1s0jbrbvbdw4c",
    "updatedAt": "2024-05-28T09:02:41.673Z",
    "deletedAt": "2024-05-28T09:02:41.673Z"
  }
]

The second key is revoked. Live keys have no deletedAt key at all rather than a null one.

#POST Create an API key

Makes a new key and returns the secret. This is the only time the secret exists anywhere you can read it.

In the app: The create key dialog under settings, which shows you the secret once and then can't get it back.

POST /api/keys

Auth: Not available to API keys.

Creating a key also needs an active subscription, where listing and revoking don't. That way someone whose subscription has lapsed can still clean up after themselves.

#Body

When proof of work is enabled on the server, the body also has to carry a solved challenge. That's part of the app's sign-up and key-creation flow, not something you'd assemble by hand.

#Response

An API key object with one extra field:

{
  "apiKeyId": "key_01hy4rfqk8z4xv1c2v44cf6abc",
  "name": "Budget sync script",
  "createdAt": "2024-06-11T20:14:03.882Z",
  "createdBy": "user_01fpwx3sdm7kb1s0jbrbvbdw4c",
  "updatedAt": "2024-06-11T20:14:03.882Z",
  "secret": "lhn735qsv3ehg5mflhpp4kcugeitxhwbb4om4oi5uqsi5bfqejgq"
}

Take apiKeyId and secret and export them as MONETR_API_KEY_ID and MONETR_API_KEY_SECRET, and every example on this site works as written. The quickstart picks up from there.

#Errors

#DELETE Revoke an API key

Turns off a key. Anything using it starts failing with a 401 immediately.

In the app: The revoke button in the API keys table.

DELETE /api/keys/:apiKeyId

Auth: Not available to API keys.

#Path parameters

Returns 200 with an empty body. Revoking is a soft delete: the record stays, with deletedAt set, so a revoked key still shows up in the list.

When proof of work is enabled, this takes a body carrying a solved challenge. When it isn't, it takes no body at all.

#Errors