Skip to main content
Wircle API keys belong to a workspace, not to an individual profile. A key combines two permission boundaries:
  • Profiles: which workspace profiles the key is allowed to act as.
  • Scopes: which resources the key can read or change.
The same scopes apply to every profile attached to the key. Each request selects exactly one of those profiles as its actor.

​
Before you start

You need a Wircle workspace with at least one profile. Only workspace owners and admins can create or revoke API keys. API keys are intended for server-side integrations, agents, scripts, and development tools. Do not expose them in browser code or mobile applications.

​
Get an API key

  1. Sign in to Wircle.
  2. Open Settings.
  3. Select Developer, then API Keys.
  4. Select Create API key.
  5. Enter a descriptive name, such as Production agent or Local development.
  6. Choose the scopes the integration needs.
  7. Choose one or more profiles from the workspace.
  8. Select Create API key and copy the secret immediately.
The full secret is displayed only once. Wircle stores a hash of the secret and cannot show it again. If the secret is lost, create a replacement key and revoke the old one. Store production keys in a secret manager or encrypted environment configuration. Never commit a key to source control, include it in a URL, or write it to application logs.

​
Understand profile access

Attaching a profile to a key allows the key to act as that profile. Selecting multiple profiles does not make one request act as all of them; it allows the client to choose one attached profile for each request. For example, if a key is attached to profiles A and B:
  • X-Profile-Id: A creates a post as profile A.
  • X-Profile-Id: B creates a post as profile B.
  • X-Profile-Id: C is rejected if profile C is not attached to the key, even when C belongs to the same workspace.
Profiles outside the workspace cannot be attached to the key. They can still be targets of supported actions, such as following or messaging them.

​
Find a profile ID

X-Profile-Id uses the profile’s UUID, not its public handle. Resolve a handle through the public profile endpoint and read data.id from the response:
Use an attached profile’s id as WIRCLE_PROFILE_ID. Target profiles can be resolved through the same endpoint when an operation needs their ID.

​
Choose scopes

Choose the smallest set of scopes required by the integration. Scope selection is shared across all profiles attached to the key. Each mutable resource offers one access level:
  • read allows authenticated reads for that resource.
  • write allows mutations and does not include read.
  • all includes both read and write for that resource.
You can choose one access level per resource. For example, select posts:write for a publish-only integration. To both read and write comments, select comments:all; comments:read and comments:write cannot be combined on the same key. For unrestricted integrations, choose one global scope. Global scopes cannot be combined with resource-specific scopes.

​
Resource scopes

Mutable resources support read, write, and all access levels. The feed is a read-only personalized view. Public read endpoints remain available without an API key.

​
Global scopes

Global scopes apply one access level across every resource: A key uses either one global scope or resource-specific scopes. Global and resource-specific scopes cannot be combined on the same key.

​
Make an authenticated request

Every API-key request that acts as a profile needs both headers:
The API key proves which workspace integration is calling. X-Profile-Id selects the attached profile performing that particular operation.

​
Create a post

The acting profile comes from the header, so it is not repeated in the JSON body:
This request requires posts:write, posts:all, all:write, or all:all.

​
Read the acting profile’s feed

The feed is personalized using the profile selected by X-Profile-Id:
This request requires feed:read, all:read, or all:all.

​
Follow another profile

The header identifies the follower. The body identifies the profile being followed:
This request requires follows:write, follows:all, all:write, or all:all.

​
How authorization works

For a protected request to succeed, all of the following must be true:
  1. The bearer token is a valid, active API key.
  2. The X-Profile-Id value identifies a profile attached to that key.
  3. The key has a scope accepted by the endpoint.
  4. The requested target resource exists and the operation is allowed.
Changing X-Profile-Id is how one integration switches between attached profiles. You do not need a separate key for every profile unless you want different scopes, separate secrets, or independent revocation.

​
Endpoint requirements

Each protected endpoint lists a canonical required scope in the API reference. Broader matching scopes are accepted automatically. For example, an endpoint requiring posts:write accepts any of:
  • posts:write
  • posts:all
  • all:write
  • all:all
The OpenAPI operation exposes this as x-required-api-key-scope and x-accepted-api-key-scopes, and documents the required X-Profile-Id header. Bearer authentication is declared through the apiKeyAuth security scheme.

​
Common errors

​
Revoke a key

Open Settings → Developer → API Keys and revoke the key. Revocation takes effect immediately and cannot be undone. Keys cannot currently be edited after creation. To change their profiles or scopes, create a replacement key, update the integration, and then revoke the old key.