Security & Authentication

RAPS supports APS OAuth workflows through a small, stable command surface:

raps auth test for 2-legged client-credentials validation
raps auth login for interactive 3-legged user auth
raps auth login --device for headless/device-code login
raps auth status, raps auth whoami, and raps auth inspect for verification
raps auth logout to clear stored 3-legged tokens

2-Legged (Client Credentials)

Use 2-legged credentials for CI/CD and server automation against app-owned resources.

export APS_CLIENT_ID="your-client-id"
export APS_CLIENT_SECRET="your-client-secret"

# Validate credentials
raps auth test

When to use:

CI/CD pipelines
Batch uploads/translations
Non-user workflows on OSS and derivative APIs

Use 3-legged auth when you need user-context access (ACC/BIM 360 projects, hubs, user-scoped data).

export APS_CLIENT_ID="your-client-id"
export APS_CLIENT_SECRET="your-client-secret"

# Opens browser and stores tokens securely
raps auth login

You can choose scope presets for faster setup:

# Examples: all, viewer, editor, storage, automation, admin
raps auth login --preset viewer

Device Code Flow (Headless)

For SSH, containers, and environments without a local browser:

export APS_CLIENT_ID="your-client-id"
export APS_CLIENT_SECRET="your-client-secret"

raps auth login --device

RAPS prints a verification URL and code. Complete the auth on another device, then continue in the same terminal.

Verify and Inspect Auth State

# Show auth state
raps auth status

# Show current 3-legged user profile
raps auth whoami

# Inspect token details (scopes, expiry)
raps auth inspect

# CI guard: fail if token expires soon
raps auth inspect --warn-expiry-seconds 3600

Token Lifecycle

RAPS stores tokens in OS keychain-backed storage (or secure file fallback when keychain is unavailable).

# Clear stored 3-legged tokens
raps auth logout

# Confirm cleared state
raps auth status

Notes:

Access token refresh for 3-legged/device flow is automatic when refresh token is valid.
For 2-legged flows, generate a fresh token by running commands with valid client credentials.

Profiles and Environment Isolation

Use config profiles for multiple environments (prod/staging/sandbox):

# Create profile containers
raps config profile create production
raps config profile create staging

# Switch active profile
raps config profile use production

# List and inspect profile state
raps config profile list
raps config profile current

MCP Server Authentication

For AI assistants, pass credentials through MCP config and start raps mcp.

{
  "mcpServers": {
    "raps": {
      "command": "raps",
      "args": ["mcp"],
      "env": {
        "APS_CLIENT_ID": "your-client-id",
        "APS_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

If your assistant needs user-context operations, authenticate first:

raps auth login
raps mcp

Headless variant:

raps auth login --device
raps mcp

Troubleshooting

`Not authenticated` in user-context commands

raps auth login
raps auth status

Headless host cannot open browser

raps auth login --device

Credentials are set but `auth test` fails

Check env vars and rerun:

echo "$APS_CLIENT_ID"
raps auth test

Token expiry checks in CI

raps auth inspect --warn-expiry-seconds 1800

Quick Reference

Scenario	Command
Validate 2-legged creds	`raps auth test`
Login (browser)	`raps auth login`
Login (device flow)	`raps auth login --device`
Show auth state	`raps auth status`
Show current user	`raps auth whoami`
Inspect token claims/expiry	`raps auth inspect`
Remove stored 3-legged tokens	`raps auth logout`
Start MCP server	`raps mcp`