Authentication

Sending a key

Every request carries the key in an Authorization header:

curl https://gateway.octopusoperations.co.za/v1/tasks \
  -H "Authorization: Bearer oct_live_..."

Send nothing and you get a 401 that tells you exactly what was expected: an error message is documentation that arrives when you need it:

{
  "success": false,
  "error": "Send your key as `Authorization: Bearer oct_live_…`.",
  "version": "v1"
}

The life of a key

The step that catches people is Shown. The full key is returned exactly once, at creation. Octopus keeps only a hash afterwards, so it cannot be shown to you again by anyone. There is no support process that recovers it, because there is nothing to recover.

Revoked is immediate and needs no deploy on your side. The next request with that key is refused with "That key is not valid.", measured in the same second. If a key leaks, revoking it is the whole remedy.

You never send an organisation id

A key belongs to exactly one organisation, so Octopus takes the organisation from the key and ignores any you send. There is nothing to configure, and no way to point a key at a tenant it does not belong to: a query string naming another organisation is quietly disregarded rather than honoured.

Two transports, one key

The same key authenticates the realtime channel. Where REST takes a header, Socket.IO takes it in the handshake:

import { io } from "socket.io-client";

const socket = io("https://gateway.octopusoperations.co.za/v1", {
  transports: ["websocket"],
  auth: { apiKey: process.env.OCTOPUS_API_KEY },
});