Authentication

1ctl authenticates with the Satusky API using an API token. Every request sends the token as an x-satusky-api-key header. There are no OAuth flows, no browser redirects — it’s just a token.

Get a token

Tokens are issued from the Satusky dashboard under Settings → API Tokens. Create a token, copy it immediately — it won’t be shown again.

Tokens look like: sat_xxxxxxxxxxxxxxxxxxxxxxxx

Log in

1ctl auth login --token sat_xxxxxxxxxxxxxxxxxxxxxxxx

1ctl validates the token against the API, then writes the authenticated context to ~/.satusky/context.json.

Expected output:

Authenticated as [email protected] (org: my-org)
Context saved to ~/.satusky/context.json

Check auth status

1ctl auth status

Expected output:

Logged in as: [email protected]
Organization: my-org
API URL:      https://api.satusky.com/v1/cli
Token:        sat_xxxx...xxxx (last 4: xxxxx)

If you’re not authenticated:

Not logged in. Run: 1ctl auth login --token <token>

Log out

1ctl auth logout

This removes the stored token from ~/.satusky/context.json. It does not revoke the token server-side — do that from the dashboard if you need to invalidate it.

CI/CD: environment variable

For automated environments (GitHub Actions, GitLab CI, Buildkite, etc.) do not write a context file. Use the environment variable instead:

SATUSKY_API_KEY=sat_xxxxxxxxxxxxxxxxxxxxxxxx 1ctl deploy

When SATUSKY_API_KEY is set, 1ctl uses it directly and ignores ~/.satusky/context.json. This makes it safe to run in ephemeral CI environments without managing credential files.

In GitHub Actions:

- name: Deploy to Satusky
  env:
    SATUSKY_API_KEY: ${{ secrets.SATUSKY_API_KEY }}
  run: 1ctl deploy

Store the token as a repository secret (SATUSKY_API_KEY) in your CI provider.

Profiles

Profiles let you manage multiple API endpoints and tokens — for example, separate credentials for development, staging, and production.

Each profile is stored in ~/.satusky/profiles.json. A profile stores an API URL and a token.

Create a profile

1ctl profile create dev --url https://dev-api.satusky.com --token sat_dev_xxxxxxxx

1ctl profile create prod --url https://api.satusky.com --token sat_prod_xxxxxxxx

List profiles

1ctl profile list

  NAME    URL                               ACTIVE
  dev     https://dev-api.satusky.com
* prod    https://api.satusky.com           true

The * marks the active profile.

Switch profiles

1ctl profile use dev

All subsequent commands use the dev profile’s API URL and token.

Use a profile for a single command

1ctl --profile prod deploy

The --profile flag overrides the active profile for that command only. Useful when you want to deploy to production from a terminal where dev is active.

Delete a profile

1ctl profile delete dev

How it works under the hood

Every 1ctl request includes the resolved token as an HTTP header:

x-satusky-api-key: sat_xxxxxxxxxxxxxxxxxxxxxxxx

The Satusky API backend validates the token against the api_tokens table in PostgreSQL and resolves the associated organization. Unauthenticated requests return 401. Invalid tokens return 403.

The resolution priority for the token is:

1. --profile <name> flag (if provided)
2. SATUSKY_API_KEY environment variable
3. Active profile from ~/.satusky/profiles.json
4. Default context from ~/.satusky/context.json

Security

Tokens are stored in plaintext in ~/.satusky/context.json and ~/.satusky/profiles.json. Protect these files:

chmod 600 ~/.satusky/context.json
chmod 600 ~/.satusky/profiles.json

Do not commit these files to version control. They are not placed in your project directory, but confirm your global .gitignore does not accidentally include ~/.satusky/.

Rotate tokens regularly from the dashboard. If a token is compromised, revoke it immediately from Settings → API Tokens.