Authentication

Every Akarso command needs an API key to authenticate with the Akarso API. Keys have an ak_ prefix.

Signing up and creating an API key is free — a subscription is only needed to create and publish posts (see pricing).

The easiest way is the CLI browser login:

1akarso auth login

This opens a browser window where you sign in and approve the CLI. An API key is automatically created and saved.

You can also create profile-pinned keys manually from the dashboard after signing in with Google.

Org and profile scope

Every API key belongs to one org and is pinned to one profile (workspace) in that org. A profile holds its own connected accounts, posts, and drafts.

When you create a key in the dashboard, choose the profile it should target. CLI login creates a key for the current/default profile.

ak_ API key ──> org membership check ──> pinned profile ──> connected accounts + posts

Overriding the profile

You can override the pinned profile per-command with --profile:

12345# List profiles to find their IDs
akarso profiles list

# Post from a different profile without creating a new key
akarso posts create --text "Hello!" --platforms x --profile 01JXYZ...

The --profile flag works on every command. The profile must belong to the same org as the API key. You can also set AKARSO_PROFILE_ID as an environment variable.

Priority	Source
1	`--profile` flag
2	`AKARSO_PROFILE_ID` env var
3	API key's pinned profile
4	Org's default profile

REST API headers

Raw REST API requests should send the key as a bearer token:

12curl https://akarso.co/api/v2/profiles \
  -H "Authorization: Bearer $AKARSO_API_KEY"

To override the profile in REST calls, add the x-akarso-profile-id header:

123curl https://akarso.co/api/v2/posts \
  -H "Authorization: Bearer $AKARSO_API_KEY" \
  -H "x-akarso-profile-id: 01JXYZ..."

The profile must belong to the key's org. Without the header, the key's pinned profile is used.

Manual key setup

If you already have an API key:

1akarso auth set --key ak_your_key_here

Resolution priority

The CLI looks for the API key in this order:

Priority	Source	Example
1	`--api-key` flag	`akarso posts list --api-key ak_xxx`
2	`AKARSO_API_KEY` env var	`export AKARSO_API_KEY=ak_xxx`
3	Config file	`~/.akarso/config.json`

Config file

The config file lives at ~/.akarso/config.json:

123{
  "apiKey": "ak_your_key_here"
}

The akarso auth login and akarso auth set commands write this file automatically.

Verify your key

1akarso auth check

This calls the Akarso API to verify the key is valid.

Environment variables

Variable	Description
`AKARSO_API_KEY`	API key for authentication
`AKARSO_PROFILE_ID`	Profile ID to override the key's pinned profile
`AKARSO_API_URL`	Custom API base URL (for development)

Ask AI about this page

The --api-key flag is useful for one-off commands or when switching between multiple keys. For regular use, set the env var or save to the config file.