> For the complete documentation index, see [llms.txt](https://docs.toolkit.equs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toolkit.equs.ai/standards/issuance/flow-2/configuration-authorization-server.md).

# Configuration: Authorization Server

Configure your Authorization Server and register it with the platform

The Holder authenticates at your Authorization Server, and the wallet presents the resulting access token to the platform. The platform takes no part in the authentication itself - it only verifies the token.

The `sub` in that token is the `sub` your [Attribute Provider](/standards/issuance/configuration-attribute-provider.md) is then asked about.

It is configured **per Issuer** - unlike the Attribute Provider, which is per Tenant.

### 1. Configure your Authorization Server

* **Discovery** at `{url}/.well-known/openid-configuration` - the wallet can't start without it.
* **Pushed Authorization Requests** (RFC 9126) are recommended.
* **A wallet client** with the `authorization_code` grant, the wallet's redirect URI registered, and able to grant the scope you register in step 2.
* **JWT access tokens**, verifiable against your JWKS. Opaque tokens and introspection aren't supported.

| Token claim         | Requirement                                                   |
| ------------------- | ------------------------------------------------------------- |
| `iss`               | Exactly the registered `url`                                  |
| `aud`               | At least one value from `allowedAudiences`                    |
| `scope`             | Contains the registered scope                                 |
| `sub`               | Present - this is what your Attribute Provider is asked about |
| `exp`, `nbf`, `iat` | Valid                                                         |

If a token carries `authorization_details` (RFC 9396), they take precedence over `scope` and must name the credential being requested.

### 2. Register it with the platform

One call per Issuer. Authenticate with your agent client, as for the Attribute Provider registration - see [Authentication](/standards/api/authentication.md).

{% hint style="info" icon="rectangle-api" %}
All calls mentioned on this page are on the [Control API](https://docs.toolkit.equs.ai/standards/issuance/flow-2/pages/MvAvsnLQU3ER2hOIIDU2#id-2.4.1-apis).
{% endhint %}

## Upsert Issuer Authorization Server config

> Create or replace the external Authorization Server configuration of an Issuer. Returns 201 on create, 200 on replace. Secrets are write-only.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Issuer","description":""}],"security":[{"sp":[]},{"tenant":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."},"tenant":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Tenant. Token of a Tenant machine client or of a Tenant portal user, carrying the `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"UpsertIssuerAuthorizationServerRequest":{"type":"object","properties":{"url":{"type":"string","description":"Authorization Server issuer identifier (RFC 8414): advertised in `authorization_servers` AND the value the token `iss` must equal."},"jwksUri":{"type":"string","description":"JWKS endpoint of the Authorization Server. JWKS is the only supported token-validation method."},"allowedAudiences":{"description":"Audiences accepted in the token `aud`. At least one must match; an empty list skips the check.","type":"array","items":{"type":"string"}},"scope":{"type":"string","description":"The OAuth2 scope registered for this issuer at the Authorization Server. An issuer serves ONE scope across every credential configuration; it is applied to the served metadata on upsert. Must be unique among issuers registered at the same Authorization Server."}},"required":["url","jwksUri","allowedAudiences","scope"]},"UpsertIssuerAuthorizationServerResponse":{"type":"object","properties":{"id":{"type":"string","description":"Authorization server configuration unique ID"},"url":{"type":"string","description":"Authorization Server issuer identifier (RFC 8414); the token `iss` must equal it"},"jwksUri":{"type":"string","description":"JWKS endpoint of the Authorization Server. JWKS is the only supported token-validation method."},"allowedAudiences":{"description":"Audiences accepted in the token `aud`. At least one must match; an empty list skips the check.","type":"array","items":{"type":"string"}},"scope":{"type":"string","description":"The single OAuth2 scope this issuer serves for every credential configuration"},"createdAt":{"format":"date-time","type":"string","description":"Date and time the authorization server configuration was created."},"updatedAt":{"format":"date-time","type":"string","description":"Date and time the authorization server configuration was last updated."}},"required":["id","url","jwksUri","allowedAudiences","scope","createdAt","updatedAt"]}}},"paths":{"/api/v1/issuers/{id}/authorization-server":{"put":{"description":"Create or replace the external Authorization Server configuration of an Issuer. Returns 201 on create, 200 on replace. Secrets are write-only.","operationId":"IssuerController_upsertAuthorizationServer_api/v1","parameters":[{"name":"id","required":true,"in":"path","description":"Issuer unique ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertIssuerAuthorizationServerRequest"}}}},"responses":{"200":{"description":"When an existing Authorization Server configuration is replaced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertIssuerAuthorizationServerResponse"}}}},"201":{"description":"When the Authorization Server configuration is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertIssuerAuthorizationServerResponse"}}}},"400":{"description":"When the configuration is incoherent (method/params mismatch, invalid URLs)."},"404":{"description":"When no issuer exists with such id, or the issuer has no Authorization Server configuration."}},"summary":"Upsert Issuer Authorization Server config","tags":["Issuer"]}}}}
```

* **This is what turns Flow 2 on for the Issuer.** Deleting it reverts the Issuer to pre-authorized only, and its tokens stop being accepted immediately.
* **Your server is added alongside the platform's own**, so Flows 1 and 3 keep working on the same Issuer.
* `url` and `jwksUri` must be public HTTPS.
* **One scope per Issuer**, applied to every credential it offers, and unique among Issuers on the same Authorization Server - a collision is rejected with `invalid_as_config`.
* **The scope can't change while Offers are pending**, since they carry the old one.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.toolkit.equs.ai/standards/issuance/flow-2/configuration-authorization-server.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.