Skip to content

Using the developer API

Minting an API token with read and write scopes, what the ninety-day lifetime means, where the OpenAPI contract lives, and what the request log does and does not record.

Updated

The developer console mints the tokens your own software uses to call the Social Studio API. Tokens belong to you as a person, not to an organisation, and every call also names the organisation it acts on.

There are exactly two scopes. Read covers requests that only read; write covers requests that change something. Write does not imply read: a token that should do both must carry both.

Every token expires. Ninety days is the maximum and the default, and there is no such thing as a token that never expires here.

BEFORE YOU START

  • A signed-in account. The console needs no particular role, because the tokens are yours.
  • Two-factor authentication or another step-up method, because minting and rotating a token asks for a fresh security check.
  • The organisation identifier you will send with each request.

STEPS

  1. Open Developer, or go to /app/developer.
  2. Read the reference card: the base address, the link to the OpenAPI contract, and the runnable examples built from your own deployment's address.
  3. Name the token, choose how long it should last, and tick read, write or both.
  4. Satisfy the security check when it is asked for.
  5. Copy the token immediately. It is shown once and never again.
  6. Send it as a bearer token, with the organisation header naming the organisation you are acting on.
  7. Rotate a token to replace it with a fresh one carrying the same name and scopes, or revoke one you no longer need.

WHAT YOU SHOULD SEE

The token, once, with the warning that it will not be shown again, and then the token listed by name, scopes and expiry. Recent requests appear in the table underneath.

WHAT THIS WILL NOT DO

  • It will not show a token again. Rotate it if you lost it.
  • It will not mint a token that lasts more than ninety days. The expiry field on the page suggests longer values and mentions never expiring; the server refuses anything over ninety and always sets one. Treat ninety as the limit.
  • It will not record request bodies, headers or query strings. The request log is metadata only, kept for thirty days by default.
  • It will not version the API. There is one version and no negotiation header.

WORTH KNOWING

Minting, rotating and revoking are each written to the organisation's audit trail. The raw token is never recorded anywhere, in the log or the trail.

IF IT DOES NOT WORK

  • "This credential is not permitted to call the REST API." means the token was minted for something else, such as an assistant connection.
  • "This credential does not carry the write scope required for this request." means you minted a read-only token.
  • "This action needs a fresh security check." is the step-up prompt. Enter a code from your authenticator.
  • "That token does not exist." means it was already revoked, or belongs to another account.
  • "Too many requests. Please retry shortly." is the rate-limit answer. Limits are per endpoint rather than global; minting is twenty a minute.
  • "Your recent requests couldn't be loaded. This doesn't affect your tokens or the API." means the log failed to load and nothing else.
  • "This deployment does not carry the OpenAPI contract." means the specification file has not been staged on this deployment.

COMMON QUESTIONS

Where is the full API reference?

At the OpenAPI address linked from the page, served unauthenticated.

Can somebody else's token act on my organisation?

Only if they are a member of it with the permissions the endpoint requires. A token carries the person's access, not more.

  • Connecting an assistant with MCP

    Minting an MCP token, the eleven tools the server exposes, and the exact state of the n8n node, the Make app definition and Zapier.

  • Receiving webhooks

    Registering an endpoint, the two events Social Studio sends, how to verify a signature, and the retry and replay behaviour you should build for.

  • Securing your account

    Turning on two-factor authentication, keeping recovery codes, ending browser sessions and revoking credentials, and what the step-up check is for.