# Sign-in for your users

An application lets Introspection verify each end user, so their work is theirs and partners can trust who they are.

An **application** is a client ID your end users sign in through. Use one when
Introspection itself should verify the end user; if your backend can vouch for
them, an [API key or service account](/identity/credentials) is enough.

**You need:** a Max or Enterprise plan for every type except `service-account`.

## Choose an application type

Type and environment are fixed at creation. Create applications
in **Project settings**, **Applications**, or with `introspection applications create`.

| Dashboard label | `--type` | End users sign in | Plan |
| --- | --- | --- | --- |
| Server credentials | `service-account` | They don't; your backend authenticates ([Credentials](/identity/credentials#create-a-service-account)) | Any |
| Federated authentication | `jwks` | With your identity provider | Max, Enterprise |
| Hosted login | `spa` | On an Introspection login page | Max, Enterprise |
| Native app | `native` | In your app, with an emailed code | Max, Enterprise |

Every end user who signs in becomes a `customer` member under **More**, **Users**.

## Sign in end users with your identity provider

1. Create a `jwks` application for your issuer (any OIDC issuer with a JWKS: Auth0, Okta, Supabase Auth):
   ```bash
   introspection applications create --type jwks --name "Acme web" \
     --environment production --issuer https://<ref>.supabase.co/auth/v1
   ```
2. Optional: to require a specific audience on the provider's JWT, attach the issuer with it:
   ```bash
   introspection applications idps create --app <application-id> \
     --issuer https://<issuer> --audience-client-id <expected-aud>
   ```
3. Your backend exchanges the end user's ID token for an Introspection token, then opens the runner: [federated broker](/patterns/web-chat#2-add-the-broker-route).

Each end user becomes member `<idp>:<sub>`. A backend can't act as them with
`user_id` (that names a separate `user:<id>` member): exchange their token, or
use an [Admin Agent key](/identity/agents#create-an-admin-agent-key).

## Use hosted login

Create an `spa` application with at least one `--redirect-uri`. The browser
redirects to an Introspection login page (authorization code with PKCE) and your
app exchanges the code. Outside development the page must broker to your own
identity provider: attach it with `applications idps create` (`--issuer`,
`--client-id`, `--client-secret`).

## Build a native app

| Your users sign in with | Do |
| --- | --- |
| Your own identity provider (Okta, or Google's ID token with issuer `https://accounts.google.com`) | A `jwks` application with that issuer. The app exchanges the provider's token on the device |
| Introspection accounts (an emailed code) | A `native` application ([email-code sign-in](/reference/authentication#native-application-email-code-sign-in)) |

REST routes for a native app

These tokens can't look up runtimes: get `runtime_id` (a version ID) from your
backend or config. The Swift package is
`https://github.com/introspection-org/introspection-swift-sdk` (product
`IntrospectionSDK`).

| Step | REST route |
| --- | --- |
| Start a task (its ID is the conversation ID) | `POST /v1/tasks` |
| Stream AG-UI events | `GET /v1/tasks/<id>/runs/<run-id>/stream` |
| Send the next message | `POST /v1/tasks/<id>/runs` with `prompt` |
| Answer an [interrupt](/patterns/ask-the-user) | `POST /v1/tasks/<id>/runs` with `resume` |

## Tell a partner who the end user is

1. Link the partner's MCP server or API endpoint to an application by its UUID (not the client ID):
   ```bash
   introspection bindings mcp connect --mcp-server-id partner-tools \
     --endpoint-url https://mcp.partner.example/mcp --authorized-application <application-uuid>
   introspection bindings endpoints create --kind api --name partner-api \
     --endpoint-url https://api.partner.example --authorized-application <application-uuid>
   ```
   It cannot be combined with `--connector` or a stored `Authorization` header.
2. Give the partner the issuer, built from the client ID: `https://api.introspection.dev/v1/applications/<client-id>`. The JWKS is at `<issuer>/.well-known/jwks.json`, and the issuer serves OpenID discovery.

Each call then carries `Authorization: Bearer <ES256 JWT>` naming the end user.

JWT claims

| Claim | Value |
| --- | --- |
| `iss` | The issuer above |
| `sub` | `user:<id>` for API-key `user_id` tasks; the partner's own user ID for `jwks` apps; else the Introspection member ID. `sub_type` says which |
| `aud` | The endpoint's audience setting, else its URL |
| `type` | `identity_assertion` or `identity_attribution` ([trust levels](/identity/agents#decide-how-much-a-partner-trusts-the-end-user)) |
| `member_id` | The member; absent for API-key `user_id` tasks |
| `task_id`, `azp`, `exp` | Task, application, about one hour |

The JWT proves who the end user is. It grants nothing: the partner still
decides what that end user may do.

To rotate the signing key, run `introspection applications keys create --app <application-id>`.
Delete the old key once partners that cache keys have updated.

## Verify

`introspection applications list` shows the application. After an end user
signs in, they appear under **More**, **Users**.

## Next

- [Add a chat to your web app](/patterns/web-chat)
- [Authentication reference](/reference/authentication)
- [How agents act](/identity/agents)

Sign-in for your users

An application lets Introspection verify each end user, so their work is theirs and partners can trust who they are.

An application is a client ID your end users sign in through. Use one when Introspection itself should verify the end user; if your backend can vouch for them, an API key or service account is enough.

You need: a Max or Enterprise plan for every type except service-account.

Choose an application type

Type and environment are fixed at creation. Create applications in Project settings, Applications, or with introspection applications create.

Dashboard label	`--type`	End users sign in	Plan
Server credentials	`service-account`	They don’t; your backend authenticates (Credentials)	Any
Federated authentication	`jwks`	With your identity provider	Max, Enterprise
Hosted login	`spa`	On an Introspection login page	Max, Enterprise
Native app	`native`	In your app, with an emailed code	Max, Enterprise

Every end user who signs in becomes a customer member under More, Users.

Create a jwks application for your issuer (any OIDC issuer with a JWKS: Auth0, Okta, Supabase Auth):


introspection applications create --type jwks --name "Acme web" \
  --environment production --issuer https://<ref>.supabase.co/auth/v1

Optional: to require a specific audience on the provider’s JWT, attach the issuer with it:


introspection applications idps create --app <application-id> \
  --issuer https://<issuer> --audience-client-id <expected-aud>

Your backend exchanges the end user’s ID token for an Introspection token, then opens the runner: federated broker.

Each end user becomes member <idp>:<sub>. A backend can’t act as them with user_id (that names a separate user:<id> member): exchange their token, or use an Admin Agent key.

Create an spa application with at least one --redirect-uri. The browser redirects to an Introspection login page (authorization code with PKCE) and your app exchanges the code. Outside development the page must broker to your own identity provider: attach it with applications idps create (--issuer, --client-id, --client-secret).

Build a native app

Your users sign in with	Do
Your own identity provider (Okta, or Google’s ID token with issuer `https://accounts.google.com`)	A `jwks` application with that issuer. The app exchanges the provider’s token on the device
Introspection accounts (an emailed code)	A `native` application (email-code sign-in)

REST routes for a native app

These tokens can’t look up runtimes: get runtime_id (a version ID) from your backend or config. The Swift package is https://github.com/introspection-org/introspection-swift-sdk (product IntrospectionSDK).

Step	REST route
Start a task (its ID is the conversation ID)	`POST /v1/tasks`
Stream AG-UI events	`GET /v1/tasks/<id>/runs/<run-id>/stream`
Send the next message	`POST /v1/tasks/<id>/runs` with `prompt`
Answer an interrupt	`POST /v1/tasks/<id>/runs` with `resume`

Tell a partner who the end user is

Link the partner’s MCP server or API endpoint to an application by its UUID (not the client ID):


introspection bindings mcp connect --mcp-server-id partner-tools \
  --endpoint-url https://mcp.partner.example/mcp --authorized-application <application-uuid>
introspection bindings endpoints create --kind api --name partner-api \
  --endpoint-url https://api.partner.example --authorized-application <application-uuid>

It cannot be combined with --connector or a stored Authorization header.

Give the partner the issuer, built from the client ID: https://api.introspection.dev/v1/applications/<client-id>. The JWKS is at <issuer>/.well-known/jwks.json, and the issuer serves OpenID discovery.

Each call then carries Authorization: Bearer <ES256 JWT> naming the end user.

JWT claims

Claim	Value
`iss`	The issuer above
`sub`	`user:<id>` for API-key `user_id` tasks; the partner’s own user ID for `jwks` apps; else the Introspection member ID. `sub_type` says which
`aud`	The endpoint’s audience setting, else its URL
`type`	`identity_assertion` or `identity_attribution` (trust levels)
`member_id`	The member; absent for API-key `user_id` tasks
`task_id`, `azp`, `exp`	Task, application, about one hour

The JWT proves who the end user is. It grants nothing: the partner still decides what that end user may do.

To rotate the signing key, run introspection applications keys create --app <application-id>. Delete the old key once partners that cache keys have updated.

Verify

introspection applications list shows the application. After an end user signs in, they appear under More, Users.