[a]authored byinflow
Guide

Basic

An AEP Service can issue an HTTP Basic username and password after enrollment. The Agent constructs the Basic header locally; it does not choose or submit the password.

When Basic fits

The basic grant type serves a Service that already uses HTTP Basic authentication for protected resources. Grant lets that Service issue a reusable credential to an enrolled Agent after verifying its AEP identity. The Agent then presents the issued credential to eligible resources without signing a new assertion for every request. The password, and the header made from it, are bearer secrets that need careful storage and revocation.

Receive the username and password

The Agent invokes Grant with a fresh baseline assertion using op=grant, a non-empty Idempotency-Key, and grant_type equal to basic. It may request Service-defined scopes and supply an optional display label. It never supplies a password. This example uses an illustrative /aep/ endpoint base:

POST /aep/grant HTTP/1.1
Host: api.example.com
Content-Type: application/aep+json
Authorization: AEP <jwt>
Idempotency-Key: 81070a57-01cd-4862-86a4-2926b84ea43a

{"grant_type":"basic","requested_scopes":["read"]}

The Service generates both the username and password, or generates a password for a Service-owned username. It returns both values with the expiry and a stable credential_id; realm and granted scopes are optional. The values below are illustrative, not usable credentials:

{
  "credential_id": "bas_example_123",
  "expires_at": "2027-01-01T00:00:00Z",
  "password": "7Jm5xQ2pL9vN4sR8tW6yB3kZ0aH1cD5e",
  "realm": "api.example.com",
  "scopes": ["read"],
  "username": "aep_agent_abc123"
}

The Agent stores the username and password with the Service DID, expiry, any granted scopes and realm, and credential_id. That ID is for management and optional targeted Revoke; it is not the username or password and is not presented to a resource. expires_at is an RFC 3339 timestamp. Missing, null, or empty scopes means the credential has no scope-limited authorization, not that every application action is permitted.

The Service must generate a password with at least 128 bits of entropy. Generated usernames and passwords contain no control characters and must be encodable as HTTP Basic without changing their values. The Service stores passwords using strong password-storage controls rather than logging or retaining raw values in ordinary telemetry.

Construct and present the Basic field

The Grant response does not include an encoded header. The Agent joins the issued values as username:password and applies standard HTTP Basic Base64 encoding under RFC 7617—not AEP's base64url convention. For the illustrative values above, the protected request can use the ordinary carrier:

GET /v1/reports/123 HTTP/1.1
Host: api.example.com
Authorization: Basic YWVwX2FnZW50X2FiYzEyMzo3Sm01eFEycEw5dk40c1I4dFc2eUIza1owYUgxY0Q1ZQ==

A protected resource must also accept the same Basic field value in AEP-Authorization. For an operation using a payment credential in Authorization, the Agent can keep the two protocols separate:

AEP-Authorization: Basic YWVwX2FnZW50X2FiYzEyMzo3Sm01eFEycEw5dk40c1I4dFc2eUIza1owYUgxY0Q1ZQ==
Authorization: Payment <payment-credential>

Use one AEP credential carrier per request, not both. The dedicated field is for protected resources; Grant and Revoke still require baseline Authorization: AEP <jwt> with the matching operation. The Service treats an expired, revoked, malformed, unknown, or wrong-Agent Basic credential as not_recognized. Authentication alone does not authorize every application action.

Protect and retire the credential

The Agent stops presenting the credential at expires_at, never sends it to another Service or across an origin-changing redirect, and does not log the password or encoded authorization value. If the credential may have been disclosed, the Agent invokes Revoke with a fresh baseline assertion and removes its local copy after success. A Service should keep AEP-issued Basic credentials in a distinct realm or credential store when it also supports human-facing Basic credentials.

grant_type=basic Revoke targets all Basic credentials issued to the authenticated Agent. To target one credential_id, Inspect must advertise supports_per_credential_revoke as "true" for this type. Otherwise the Agent uses grant-type or all-grant-types Revoke. See Grant and Revoke for the common command contract and Revoke credentials for choosing a scope.

On this page