[Improvement] Standardize authentication field schemas

[MaryamZi]

Problem

The AFM spec recognizes several authentication types (bearer, basic, api-key, jwt, oauth2) but does not define the required or optional fields for any of them. The spec states that "additional fields are authentication-type specific," leaving it to runtimes and users to figure out what each type needs.

Of these, only bearer, basic, and api-key are implemented in runtimes today. jwt and oauth2 are recognized by the spec but have no runtime support — their field schemas need to be defined before they can be implemented.

This creates problems:

1. No validation: Runtimes can't validate auth configs against a schema — a missing token field on a bearer type is only caught at request time.
2. Inconsistency across runtimes: Different implementations may expect different field names or structures for the same auth type.
3. Poor authoring experience: Users writing .afm.md files have no spec-defined reference for what fields to provide. They rely on runtime-specific docs or trial and error.
4. Blocked implementations: jwt and oauth2 can't be implemented without first agreeing on what fields they require.

Proposal

Define the required and optional fields for each authentication type in the spec.

Proposed field schemas

bearer

Field	Required	Description
token	yes	The bearer token value

authentication:
  type: bearer
  token: "${env:API_TOKEN}"

basic

Field	Required	Description
username	yes	The username
password	yes	The password

authentication:
  type: basic
  username: "${env:SERVICE_USER}"
  password: "${env:SERVICE_PASS}"

api-key

Field	Required	Description
api_key	yes	The API key value

authentication:
  type: api-key
  api_key: "${env:API_KEY}"

jwt

TBD

oauth2

TBD

Where authentication appears

Authentication is used across multiple contexts in the spec:

• tools.mcp[].transport.authentication — MCP server connections
• model.authentication — model/provider connections
• interfaces[].subscription.authentication — webhook subscriptions

The field schema should apply uniformly regardless of where the authentication object appears.

Open questions

• JWT generation: Should the spec support runtime-side JWT signing (providing a key and claims), or only accept pre-signed tokens? If generation is supported, what fields are needed (signing_key, algorithm, claims, expiry)?
• Custom headers for API keys: Some APIs expect the key in a specific header (e.g., X-API-Key vs Authorization). Should api-key support an optional header_name field?
• Extensibility: Should runtimes be allowed to support additional auth types beyond the spec-defined set, or should unknown types be rejected?

[Thareesha98]

Proposal: Standardize authentication field schemas

Re: [Improvement] Standardize authentication field schemas (#35)

Summary

Define the required and optional fields for every authentication type, apply one uniform
schema wherever authentication appears, validate it at parse time, and resolve the
three open questions. bearer / basic / api-key are fully specified and ship now;
jwt / oauth2 get agreed field schemas in this proposal (which unblocks them) with phased
runtime support.

Common rules

authentication appears in three places, and the schema is identical in all of them:

• model.authentication
• tools.mcp[].transport.authentication
• interfaces[].subscription.authentication

1. type is required and must be one of the recognized set:
   bearer | basic | api-key | jwt | oauth2. It is matched case-insensitively.
2. Unknown type values are rejected at parse time with a clear error that lists the
   supported types (resolves Open Question 3).
3. Required fields per type are validated at parse time — fail fast at authoring/load
   time, not at request time.
4. Unknown fields are rejected per type (closed schema), so typos like tokn: or
   apikey: are caught when the .afm.md is loaded. (Exception: oauth2, whose allowed
   fields depend on grant_type — see below.)
5. Any string field may use ${env:VAR} substitution (already supported). Secrets SHOULD be
   provided via ${env:...} rather than inline.

Field schemas

bearer

Field	Required	Type	Description
token	yes	string	The bearer token value

Sent as Authorization: Bearer <token>.

authentication:
  type: bearer
  token: "${env:API_TOKEN}"

basic

Field	Required	Type	Description
username	yes	string	The username
password	yes	string	The password

Sent as Authorization: Basic base64(username:password).

authentication:
  type: basic
  username: "${env:SERVICE_USER}"
  password: "${env:SERVICE_PASS}"

api-key

Field	Required	Type	Description
api_key	yes	string	The API key value
header_name	no	string	HTTP header to carry the key. Default Authorization.

Sent as <header_name>: <api_key> (raw value, no Bearer prefix). header_name resolves
Open Question 2 — it lets api-key target APIs that expect X-API-Key, api-key, etc.

authentication:
  type: api-key
  api_key: "${env:API_KEY}"
  header_name: "X-API-Key" # optional, defaults to Authorization

jwt

Resolution of Open Question 1: Pre-signed JWTs are already expressible via bearer, so to
avoid redundancy jwt means runtime-side signing — the runtime mints and signs a JWT from
a key plus claims. Fields are aligned with http:JwtIssuerConfig (Ballerina) and standard JWT
libraries (Python).

Field	Required	Type	Description
issuer	yes	string	iss claim
audience	yes	string | string[]	aud claim
signing_key	yes	string	PEM private key / shared secret (use ${env:...} or a path)
algorithm	no	string	Signing algorithm, default RS256
key_id	no	string	kid header
subject	no	string	sub claim
custom_claims	no	map<string, any>	Extra claims to embed
expiry_seconds	no	int	Token lifetime, default 300

authentication:
  type: jwt
  issuer: "afm-agent"
  audience: "https://api.example.com"
  signing_key: "${env:JWT_PRIVATE_KEY}"
  algorithm: "RS256"
  expiry_seconds: 300

If you already hold a signed token, use bearer instead of jwt.

oauth2

grant_type is a required discriminator; the remaining required fields depend on it. The
flows mirror Ballerina's http:OAuth2*GrantConfig types.

grant_type	Required fields	Optional
client_credentials	token_url, client_id, client_secret	scopes
password	token_url, username, password, client_id, client_secret	scopes
refresh_token	refresh_url, refresh_token, client_id, client_secret	scopes
jwt_bearer	token_url, assertion	client_id, client_secret, scopes

scopes is string[].

authentication:
  type: oauth2
  grant_type: client_credentials
  token_url: "https://auth.example.com/oauth2/token"
  client_id: "${env:OAUTH_CLIENT_ID}"
  client_secret: "${env:OAUTH_CLIENT_SECRET}"
  scopes: ["read", "write"]

Resolution of the open questions

1. JWT generation → jwt denotes runtime-side signing (key + claims). Pre-signed
   tokens use bearer. Field schema is defined above.
2. Custom headers for API keys → yes, add an optional header_name (default
   Authorization).
3. Extensibility → reject unknown type values at parse time against the fixed set.
   This keeps runtimes consistent and gives authors an immediate, clear error instead of a
   late request-time failure.

Validation & consistency

The schema is enforced uniformly across all runtimes and all locations where
authentication appears, at parse time:

• A missing required field (e.g. bearer without token) is a parse error.
• An unrecognized type is a parse error listing the supported types.
• An unknown field for the given type is a parse error (closed schema).

This addresses the four problems in the issue: validation, cross-runtime consistency,
authoring experience, and unblocking jwt/oauth2.

Phasing

• Phase 1 (this issue, ship now): bearer, basic, api-key — full field schemas,
  parse-time validation, header_name, reject-unknown-types, and validation parity across
  runtimes.
• Phase 2: jwt runtime signing.
• Phase 3: oauth2 grant flows.

Until a type's runtime support lands, parsing still validates its fields and the runtime
returns a clear "<type> authentication is recognized but not yet implemented" error rather
than a generic failure.

[MohamedSabthar]

Hi @Thareesha98 @MaryamZi,

A few points worth considering:

1. Are we not planning to support mTLS for auth?

2. If there are auth types beyond the spec set, instead of failing at parse time, can't we allow a reserved prefix (x-*) for auth? That way the runtime can implement it if needed. Instead of rejecting it when the runtime actually needs it, we can have the spec allow extensions.

ex:

authentication:
  type: x-aws-sigv4
  region: "us-east-1"
  service: "bedrock"
  access_key_id: "${env:AWS_ACCESS_KEY_ID}"
  secret_access_key: "${env:AWS_SECRET_ACCESS_KEY}"
  session_token: "${env:AWS_SESSION_TOKEN}"   # optional

3. Can't we stick to the name token_url in the refresh_token grant type instead of refresh_url? In the OAuth2 world there is no separate refresh URL.

4. Any reason for not supporting the authorization_code grant type?

5. The password grant type is already deprecated. Do we need to support it?

6. In the OAuth2 case, the client may need to authenticate to the token endpoint, so we might have to introduce some fields for that too. (See https://central.ballerina.io/ballerina/oauth2/2.15.0#ClientConfiguration for the fields needed for client auth / secure socket.)

7. Is it ok to allow a free string for algorithm? Don't we need to validate this? ex: (algorithm: "none")

8. Any reason to make the audience field mandatory? In JWT it's not required by default.