# Auth Center Integration

## When to use

Use this skill whenever a task requires provisioning a user in Auth Center, granting or updating a user's access role to another application, or managing (listing, issuing, revoking) a user's API keys. Auth Center is the central SSO (single sign-on — one login shared across apps) and identity provider for all Newx apps, so any workflow that onboards a user, changes their permissions on a target app, or rotates credentials should route through here rather than touching a target app's local user table directly.

## Tools

- `http-get` — read existing state (e.g. list a user's API keys)
- `http-post` — create resources (users, app accesses, API keys)
- `http-request` — update or delete resources (e.g. revoke an API key)
- `write-file` — stage large result sets (e.g. bulk API key listings) before further processing
- `send-message` — escalate to a human when authentication fails or configuration is missing

## Playbook

1. Confirm the org has an active Integration row for Auth Center before doing anything else. If none exists, stop and use `send-message` to notify a human, naming "Auth Center" and the scopes required.
2. To onboard or find a user, call `http-post` against `/api/v1/users` with the user's email. A 200 response means the user already existed; a 201 response means a new user was created. Treat both as success.
3. To grant or update a user's access to a target application, call `http-post` against `/api/v1/app_accesses` with the user's email, the target application's app id, and the desired role. This upserts (creates or updates) the access record, so it is safe to call even if the user already has a role on that app.
4. To review a user's current API keys before issuing a new one or auditing access, call `http-get` against `/api/v1/api_keys?email=...`. This returns each key's id, name, last four characters, scopes, active status, and creation date, but never the raw token.
5. To issue a new API key, call `http-post` against `/api/v1/api_keys` with the email, a descriptive name, and the requested scopes. The response includes the raw token exactly once — if the workflow needs to hand it off downstream, use `write-file` to stage it immediately rather than re-requesting it, since it cannot be retrieved again.
6. To revoke a key that is no longer needed (rotation, offboarding, suspected compromise), call `http-request` with a DELETE against `/api/v1/api_keys/:id`, using the id discovered in step 4.
7. When a task involves auditing or migrating many users' keys at once, use `http-get` to page through results and `write-file` to stage the combined output before acting on it, rather than holding everything in memory across many calls.

## Failure modes

- A 401 or 403 response means the Integration's credentials are missing, expired, or lack the required scope. Stop immediately, do not retry blindly, and use `send-message` to escalate to a human, naming "Auth Center" and the specific scope or permission needed.
- A missing Integration row for the org means Auth Center was never connected. Stop and escalate the same way, naming "Auth Center" as the app that needs to be configured.
- A 404 on `/api/v1/api_keys/:id` during revocation means the key was already removed or the id is stale; re-fetch the current key list via `http-get` before retrying.
- Never fabricate, log, or echo back credentials, raw tokens, or the contents of the X-App-Id / X-App-Secret headers — these are injected automatically by the Integration and are not something this skill should ever see, request, or output.

## Done when

- The requested user exists in Auth Center (confirmed by a 200 or 201 from `/api/v1/users`).
- Any requested app access grant has been upserted via `/api/v1/app_accesses` and reflects the intended role.
- Any requested API key has been issued, listed, or revoked as instructed, with staged results written via `write-file` when the result set is large.
- No credentials were requested, echoed, or hardcoded, and any authentication failure or missing Integration was escalated via `send-message` rather than worked around.