Home
Sign in

An API key lets a program talk to ORC8R on your behalf, so you can automate tasks such as listing nodes from a script or a continuous-integration pipeline instead of clicking through the web app. This page is a little more technical than the others; if you only use the web interface, you do not need an API key.

Creating a key

  1. Click your name or avatar in the top right and open your Profile.
  2. Scroll to the API Keys section and click Create New API Key.
  3. Enter a Purpose so you remember what the key is for (for example, "CI/CD automation").
  4. Choose an Expiration — how long the key stays valid. Options range from 1 hour up to 1 year.
  5. Click Create API Key.

The new key is shown to you once. Copy it straight away and store it somewhere safe — you will not be able to see it again. If you lose it, delete it and create a new one.

Using a key

Send the key in an Authorization header with each request, using the word Bearer followed by the key. Requests go to paths that begin with /api/.

Here is a request that returns your own account details:

curl -H "Authorization: Bearer YOUR_API_KEY" https://YOUR-ORC8R-HOST/api/auth/user

And here is one that lists the nodes you can see:

curl -H "Authorization: Bearer YOUR_API_KEY" https://YOUR-ORC8R-HOST/api/nodes/

Replace YOUR_API_KEY with the key you copied and YOUR-ORC8R-HOST with the address of your ORC8R site. The node list comes back as JSON, one page at a time, so large accounts are returned in batches.

The complete list of endpoints, with every field they accept and return, is in the API reference.

Keeping keys safe

  • Treat a key like a password. Anyone who has it can act as you. Do not paste it into emails, chat, or public code.
  • Give each key a clear purpose so you can tell them apart later.
  • Set a sensible expiration. A key that expires cannot be misused forever.
  • Delete keys you no longer need, or any you think may have leaked. In the API Keys section of your Profile, each key has a Delete button. Once deleted, a key stops working immediately, so create a replacement first if something still depends on it.
  • API reference — the full list of endpoints.
  • Nodes — what the data returned by the nodes endpoint describes.