API-first setup with the CLI

Allowly is designed so the human handles account, email verification, and billing in the dashboard, then delegates workspace setup to a coding agent or script.

The safe handoff is browser-approved allowly login. The CLI opens the dashboard, the signed-in owner approves setup access for the workspace, and the CLI stores a local credential. CLI credentials can create scopes, agent scope bundles, and runtime API keys. They cannot call /v1/check, read billing, manage users, or change passwords.

Human vs. agent responsibilities

The split is intentionally simple:

The human stays in control of account and billing decisions. The agent handles repeatable app setup inside the codebase.

What to give Codex or Claude

For a coding agent to set up Allowly correctly, it does not need dashboard access, billing access, or secret values pasted into chat. It needs a small integration brief:

Today, the CLI configures Allowly and can smoke-test runtime checks. Your coding agent still patches application code directly after reviewing the repo. A future allowly install command is planned to make that patching step safer and more repeatable.

1. Log in from the CLI

Run:

allowly login \
  --api-url https://api.allowly.ai

The CLI opens a browser page such as:

https://app.allowly.ai/cli/authorize?user_code=ABCD-2345

Sign in, confirm the workspace, and click Allow CLI. The terminal finishes automatically and stores the CLI credential locally.

For local development:

allowly login \
  --api-url http://localhost:8080

Warning:

CLI credentials are local secrets. They are stored in ~/.allowly/config.json with owner-only permissions. Do not paste them into tickets, logs, or public chat.

2. Hand setup to Codex or Claude Code

Give your coding agent the API URL and either an intended use-case seed or an existing allowly.setup.json. Do not give it your dashboard password, billing details, or personal API credentials. The agent can run allowly login; you approve the browser prompt.

Copy and paste this prompt into Codex, Claude Code, or another coding agent:

Configure Allowly for this app using the CLI.

API URL: https://api.allowly.ai
Use-case seed: email-agent
Runtime env var: ALLOWLY_API_KEY
Runtime env file: .env.local

Tasks:
1. Run `allowly login --api-url <api-url>`.
2. Run `allowly setup guide` and use it as the source of truth for CLI commands.
3. Run `allowly status` and summarize only the setup state, never secrets.
4. If `allowly.setup.json` already exists, review it and apply it.
5. If `allowly.setup.json` does not exist, either create one manually or seed one with `allowly init --use-case <use-case-seed>`.
6. Apply scopes with `allowly scopes apply allowly.setup.json`.
7. Apply agent scope bundles with `allowly bundles apply allowly.setup.json`.
8. Create a runtime API key with `allowly keys create --write-env <runtime-env-file> --var <runtime-env-var>`.
9. Optionally run `allowly check --runtime-env <runtime-env-file> --authorization-id <authorization-id> --scope <scope>` after the app has created an authorization.
10. Report the files changed and the setup actions completed.

Safety rules:
- Do not print, commit, log, or summarize the runtime API key.
- Do not print, commit, log, or summarize the CLI credential in `~/.allowly/config.json`.
- Do not overwrite an existing `allowly.setup.json` without reviewing it first.
- Do not edit app source code unless explicitly asked.
- Do not use the CLI credential for runtime requests.

For local development, change the API URL to:

API URL: http://localhost:8080

For production or hosted setup, use:

API URL: https://api.allowly.ai

After the CLI credential expires or is revoked, the agent can no longer change workspace configuration.

3. Check setup status

allowly status

This shows the workspace, signing state, billing state, number of configured scopes, number of agent scope bundles, and the next recommended setup steps.

4. Create an Allowly setup file

Run this only if you want Allowly to create a starter setup file from a use case:

allowly init --use-case email-agent

This creates allowly.setup.json:

{
  "scopes": [
    {
      "name": "email.read",
      "description": "Read user email metadata and message content.",
      "requires_confirm": false,
      "constraints_schema": {}
    },
    {
      "name": "email.send",
      "description": "Send email on behalf of the user.",
      "requires_confirm": true,
      "constraints_schema": {
        "type": "object",
        "properties": {
          "max_per_day": { "type": "integer", "minimum": 1 }
        }
      }
    }
  ],
  "agent_scope_bundles": [
    {
      "id": "email-agent-basic",
      "agent_id": "email-agent",
      "description": "Basic email assistant permissions.",
      "scopes": [
        { "name": "email.read" },
        { "name": "email.send", "constraints": { "max_per_day": 5 } }
      ],
      "requires_confirm_for": ["email.send"],
      "requires_escalation_for": [],
      "escalation_targets": {},
      "default_expiry_days": 90
    }
  ]
}

Scopes are the individual permissions your agent can request. Agent scope bundles are reusable groups of scopes that your app can use when asking a user for authorization.

Use requires_confirm_for for user approval. On Pro+ workspaces, use requires_escalation_for plus escalation_targets for third-party approval flows.

Available use-case seeds:

To list use-case seeds from the CLI:

allowly init --list-use-cases

5. Apply scopes and agent scope bundles

allowly scopes apply allowly.setup.json
allowly bundles apply allowly.setup.json

Apply commands are idempotent:

• Existing matching resources are skipped.
• Missing resources are created.
• Nothing is deleted unless a future explicit prune command is added.

6. Create the runtime API key

After scopes and agent scope bundles exist, create the runtime API key your application will use:

allowly keys create --write-env .env.local --var ALLOWLY_API_KEY

The runtime key is written to .env.local. It is not printed when --write-env is used. It is the key your backend sends as:

Authorization: Bearer allowly_l1_s001_...

Tip:

CLI credentials are for configuration. Runtime API keys are for production traffic. Keep them separate so a leaked runtime key cannot administer the workspace.

Agent-driven examples

Fresh app

Use this flow when your app does not have an Allowly setup file yet:

allowly login \
  --api-url https://api.allowly.ai

allowly status
allowly init --use-case email-agent
allowly scopes apply allowly.setup.json
allowly bundles apply allowly.setup.json
allowly keys create --write-env .env.local --var ALLOWLY_API_KEY

Expected files changed:

For local Allowly development, swap the login URL:

allowly login \
  --api-url http://localhost:8080

Existing app

Use this flow when allowly.setup.json already exists:

allowly login \
  --api-url https://api.allowly.ai

allowly status
allowly scopes apply allowly.setup.json
allowly bundles apply allowly.setup.json
allowly keys create --write-env .env.local --var ALLOWLY_API_KEY

Expected files changed:

In an existing app, ask the agent to explain any permission changes before applying them. This keeps authorization wording and scope names aligned with the product experience users will see.

Agent wires the app

After workspace setup is complete, you can ask the agent to wire Allowly into the app code. This is a separate step from CLI configuration. The CLI gives the agent the Allowly-side resources; the app patch adds the runtime checks.

Wire Allowly into this app.

Runtime API key location: .env.local
Runtime env var: ALLOWLY_API_KEY
Agent scope bundle to use: email-agent-basic

Implement:
1. Install the Allowly SDK for this project language if it is not installed.
2. Create one small Allowly client module that reads ALLOWLY_API_KEY from the server environment.
3. Add authorization creation where the user authorizes the agent.
4. Store the returned authorization_id on the app's user/account record.
5. Before each agent side effect, call Allowly check with the stored authorization_id and requested scopes.
6. If Allowly returns allow, run the action.
7. If Allowly returns confirm, show an approval step, approve the confirmation nonce, then check again.
8. If Allowly returns deny, block the action and show a clear product message.
9. Do not expose ALLOWLY_API_KEY to browser/client-side code.

Before editing, show me the files you plan to touch.
After editing, summarize the integration points and any tests you added.

This is the workflow allowly install is intended to automate later: detect the framework, add a small Allowly client module, patch the agent action path, add tests, and show a dry-run diff before writing files. Until that command ships, ask the coding agent to make these edits explicitly.

Expected app changes:

The agent should not use the CLI credential in app code. CLI credentials configure the workspace; runtime API keys power the app.

Secret safety checklist

• CLI credentials are configuration credentials. Store them only in your local Allowly CLI config.
• Runtime API keys are application credentials. Store them in .env.local, your deployment secret manager, or your CI secret store.
• Never commit CLI credentials, runtime API keys, .env.local, terminal transcripts with secrets, or chat logs containing secrets.
• Revoke CLI credentials after setup finishes if the machine or agent context is no longer trusted.
• If a secret is exposed, revoke it and create a replacement instead of trying to reuse it.