Authentication

Every request to https://api.onepostly.com needs an API key from your workspace. A key only works for its own workspace. It reaches every account and post in it, or only those of some profiles.

Create an API KeyCopy Anchor Link

None of these choices can be changed later. To change one, create a new key and delete the old one.

A key works for the whole workspace, whoever created it. When a member leaves the workspace or deletes their account, the keys they created are deleted.

ExpirationCopy Anchor Link

A key never expires by default. You can give it a lifetime of 7, 30 or 90 days, or 1 year. After that, every request with it returns 401 UNAUTHORIZED. The API Keys page shows when each key expires.

Profile AccessCopy Anchor Link

A key reaches every profile by default. You can limit it to some profiles instead, such as a key for each client.

When a key with one profile connects an account, the account goes to that profile. A key with several profiles must name one of them in profile. Without it, the request returns 400 VALIDATION_ERROR, and another profile returns 403 FORBIDDEN.

The key keeps working when you rename its profiles. You cannot delete a profile while a key is limited to it.

Restrict AccessCopy Anchor Link

A key can use the whole API by default. You can turn off parts of it, so the key can only do the work it is made for. A request to a part that is off returns 403 GROUP_DISABLED, with the part's name in details.group.

At least one part stays on.

Send the KeyCopy Anchor Link

Send the key as a bearer token in the Authorization header.

Authorization: Bearer op_YOUR_KEY

Use the SDKCopy Anchor Link

The samples in these docs read the key from the ONEPOSTLY_API_KEY environment variable.

export ONEPOSTLY_API_KEY="op_YOUR_KEY"

This request lists your accounts, so it is a quick way to check that your key works.

import { Configuration, AccountsApi } from "@onepostly/sdk";

const accountsApi = new AccountsApi(
  new Configuration({ accessToken: process.env.ONEPOSTLY_API_KEY })
);

const response = await accountsApi.listAccounts();
console.log(response);

{
  "data": [
    {
      "id": "acc_1699f4157fb643f49d2ac447491f3202",
      "platform": "linkedin",
      "displayName": "Your Brand",
      "handle": "Your Brand",
      "avatarUrl": "https://cdn.onepostly.com/avatars/yourbrand.jpg",
      "status": "active",
      "canAutoRenew": false,
      "tokenExpiresAt": "2027-05-14T10:00:00.000Z",
      "profile": "Default",
      "metadata": {},
      "createdAt": "2027-03-01T10:05:00.000Z",
      "updatedAt": "2027-03-01T10:05:00.000Z"
    },
    {
      "id": "acc_1699f4157fb643f49d2ac447491f32a8",
      "platform": "x",
      "displayName": "Your Brand",
      "handle": "yourbrand",
      "avatarUrl": "https://cdn.onepostly.com/avatars/yourbrand.jpg",
      "status": "active",
      "canAutoRenew": true,
      "tokenExpiresAt": "2027-05-14T10:00:00.000Z",
      "profile": "Default",
      "metadata": {},
      "xSubscriptionType": "None",
      "createdAt": "2027-03-01T10:00:00.000Z",
      "updatedAt": "2027-03-01T10:00:00.000Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

See SDKs to install and configure the Node.js and Python clients.

ErrorsCopy Anchor Link

In TypeScript these errors throw a ResponseError, and in Python they raise an ApiException. The response body has a requestId. Share it with support when you need help. See Errors.

Keep Keys SafeCopy Anchor Link

• Keep keys on your server. Never put them in browser or mobile code, or in version control.
• Store them in environment variables or a secret manager.
• Use a separate key for each app or environment. Then you can delete one without breaking the others.
• Use a read_only key for integrations that only read data.
• Limit a key to the profiles and parts of the API it needs.
• Give a key an expiration when it is only needed for a while.

Rotate a KeyCopy Anchor Link

Create a new key and deploy it. Then delete the old key on the API Keys page. Requests that still use the old key return 401 UNAUTHORIZED.