Skip to content
nofeb

Authenticate an AI agent with GitHub Actions or Entra ID

Trust the issuer with POST /v1/federation/issuers (kind github_actions, or entra with your tenant id), bind the exact subject and any claim conditions to a registered agent with POST /v1/federation/bindings, then have the agent POST its platform token to /oauth/token with grant_type urn:ietf:params:oauth:grant-type:token-exchange. It gets back a bearer token that lasts 15 minutes by default, has no refresh token, holds only the scopes the binding and the agent both allow, and works on the API, MCP, JMAP and the realtime stream. Nothing secret is stored on either side.

Checked against the engine on .

What do you need?

  • An org-level nofeb key with key:manage, to trust the issuer and create the binding
  • A registered agent (POST /v1/agents) with a human sponsor
  • A GitHub Actions workflow that may request an OIDC token (permissions: id-token: write), or an Azure workload with a managed identity or an Entra Agent ID agent identity

Steps

  1. 1. Give the agent a scope ceiling

    Federated sessions act as a registered agent, so mail they send is signed as that agent and lands in the audit log under its name. max_scopes on the agent caps every session it will ever get, whichever binding produced it; leave it out for no agent-level ceiling, or patch it later (an empty list removes it).

    Register the agent with a ceiling
    curl -X POST https://api.nofeb.com/v1/agents -H "Authorization: Bearer $NOFEB_ADMIN_KEY" \
      -H 'content-type: application/json' \
      -d '{"name": "triage bot", "sponsor_email": "dana@acme.example",
           "max_scopes": ["inbox:read", "message:read", "message:write", "message:send"]}'
  2. 2. Trust the issuer

    A preset fills in the issuer URL, the claim bindings compare by default and the longest token lifetime accepted. github_actions trusts https://token.actions.githubusercontent.com (or an enterprise's custom issuer with enterprise) and compares sub; entra takes your directory (tenant) id, trusts its v2.0 issuer and compares oid, the object id of the managed identity or agent identity. By default a token must be addressed to the API base URL or to api://nofeb; set audiences to accept something else. Signing keys are read from the issuer's published discovery document and key set and re-read when it rotates, so there is no secret to paste or rotate. Trusting an issuer is org-wide, so it needs an org-level key.

    GitHub Actions, and an Entra tenant
    curl -X POST https://api.nofeb.com/v1/federation/issuers -H "Authorization: Bearer $NOFEB_ADMIN_KEY" \
      -H 'content-type: application/json' -d '{"kind": "github_actions"}'
    
    curl -X POST https://api.nofeb.com/v1/federation/issuers -H "Authorization: Bearer $NOFEB_ADMIN_KEY" \
      -H 'content-type: application/json' \
      -d '{"kind": "entra", "tenant_id": "72f988bf-86f1-41af-91ab-2d7cd011db47",
           "audiences": ["api://nofeb", "00000000-1111-2222-3333-444444444444"]}'
    
    { "id": "fis_…", "kind": "entra", "name": "Microsoft Entra ID",
      "issuer": "https://login.microsoftonline.com/72f988bf-86f1-41af-91ab-2d7cd011db47/v2.0",
      "audiences": ["api://nofeb", "00000000-1111-2222-3333-444444444444"],
      "max_token_lifetime_secs": 7200, "default_subject_claim": "oid", "binding_count": 0, … }
  3. 3. Bind one workflow, or one identity, to the agent

    A binding names the issuer, the exact subject, up to ten extra claim conditions (eq, in or prefix; a JSON pointer reaches nested claims), the agent and a scope ceiling, and can confine sessions to one pod or one inbox. A GitHub subject such as repo:acme/agents:ref:refs/heads/main already pins the repository and branch; a condition on workflow_ref pins the workflow file too, so another workflow in the same repository cannot act as the agent. A binding can never grant a scope the key creating it lacks.

    Only the triage workflow on main, only one inbox
    curl -X POST https://api.nofeb.com/v1/federation/bindings -H "Authorization: Bearer $NOFEB_ADMIN_KEY" \
      -H 'content-type: application/json' \
      -d '{"issuer_id": "fis_…", "agent_id": "agt_…", "name": "triage on main",
           "subject": "repo:acme/agents:ref:refs/heads/main",
           "conditions": [{"claim": "workflow_ref", "op": "prefix",
                           "value": "acme/agents/.github/workflows/triage.yml@"}],
           "max_scopes": ["message:read", "message:send"], "inbox_id": "inb_…"}'
  4. 4. Exchange the token in GitHub Actions

    The job asks GitHub for an OIDC token addressed to api://nofeb and posts it to the token endpoint as a form. The answer is an opaque bearer token: scopes are what you request intersected with the binding and the agent (all of them if you leave scope out), it expires after 15 minutes or when the GitHub token does, whichever is first, and there is no refresh token, so the next job exchanges again. Each GitHub token is accepted once.

    A workflow step (permissions: id-token: write)
    JWT=$(curl -s -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
      "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://nofeb" | jq -r .value)
    
    curl -s https://api.nofeb.com/oauth/token \
      -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
      -d subject_token_type=urn:ietf:params:oauth:token-type:jwt \
      --data-urlencode "subject_token=$JWT" \
      -d scope="message:read message:send"
    
    { "access_token": "nfo_at_…",
      "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
      "token_type": "Bearer", "expires_in": 900, "scope": "message:read message:send" }
  5. 5. Exchange the token on Azure

    With Entra, the workload requests an access token for an application registered in your tenant that stands for nofeb, configured to issue v2.0 tokens; v1.0 tokens carry a different issuer and are refused. A v2.0 access token is addressed to that application's client id, which is why the issuer above lists it in audiences. A managed identity gets the token from the instance metadata endpoint; an Entra Agent ID agent identity presents its own v2.0 token the same way, and the binding matches its oid. Entra's uti claim makes each token single use.

    A managed identity on an Azure VM or container
    JWT=$(curl -s -H Metadata:true \
      "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=api://nofeb" \
      | jq -r .access_token)
    
    NOFEB_TOKEN=$(curl -s https://api.nofeb.com/oauth/token \
      -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
      -d subject_token_type=urn:ietf:params:oauth:token-type:jwt \
      --data-urlencode "subject_token=$JWT" | jq -r .access_token)
    
    curl https://api.nofeb.com/v1/inboxes/inb_…/messages -H "Authorization: Bearer $NOFEB_TOKEN"
  6. 6. Dry-run a token that is refused

    Paste a token into POST /v1/federation/test (the test_federated_token MCP tool) and nofeb runs every check the exchange would: the format and algorithm (RS256, ES256 or PS256 only), the issuer, the signature, the audience, expiry and lifetime, replay, each binding and why it does or does not match, the agent and the scopes. Nothing is issued, the token is not used up, and the answer shows only its decoded header and claims, never the token.

    Why would this token be refused?
    curl -X POST https://api.nofeb.com/v1/federation/test -H "Authorization: Bearer $NOFEB_ADMIN_KEY" \
      -H 'content-type: application/json' -d "{\"token\": \"$JWT\"}"
    
    { "would_issue": false, "result": "wrong_audience",
      "message": "aud [\"https://github.com/acme\"] is not an audience this issuer is trusted for …",
      "checks": [ { "check": "format", "ok": true, … }, { "check": "issuer", "ok": true, … },
                  { "check": "signature", "ok": true, … }, { "check": "claims", "ok": false, … } ],
      "bindings": [], … }

How do you stop a federated agent?

Delete the binding and every session it produced ends at once; delete the issuer and its bindings and their sessions go with it; revoke the agent and its sessions end and its keys stop sending. A session is only ever as wide as the binding that minted it, and a pod-bound key manages only its own pod's bindings.

Every exchange is written to the audit log as federation.token_exchange: on success with the issuer, subject, agent, binding and scopes, on refusal with the machine reason (expired, wrong_audience, no_binding, replayed and so on). The token itself is never recorded.

What a recipient sees

Mail sent through a federated session is signed as the registered agent, and the signed claims also name the external identity that acted, its issuer and subject. Verifying the message reports it beside the agent and its sponsor, so a recipient can tell which workflow or workload sent it.

What it does not do

There is no delegation (actor tokens are refused), no refresh token, and no symmetric or unsigned tokens. Google service accounts, Amazon EKS service-account tokens and any other OIDC issuer work the same way with the google, aws_eks and oidc presets.

Frequently asked questions

Can an AI agent use nofeb without an API key?

Yes. An agent running in GitHub Actions, on Azure with Entra ID or Entra Agent ID, on Google Cloud, on Amazon EKS or behind any OIDC issuer exchanges the token its platform issues for a short-lived nofeb access token. Nothing secret is stored with the agent or in nofeb.

Can any repository on GitHub get a token for my agent?

No. Only a token whose subject equals the binding's subject and that satisfies every condition matches, so a binding to repo:acme/agents:ref:refs/heads/main accepts that repository's main branch and nothing else. Tokens from GitHub that match no binding of yours are refused.

How long does a federated nofeb token last?

Fifteen minutes by default, and never longer than the external token it was exchanged for. There is no refresh token; the agent exchanges a fresh platform token when it needs another.

Status of everything on this page

Every capability named above, with its status as reconciled against the engine.

CapabilityWhat it doesStatus
Agent identity federation (no stored API key) An agent signs in with the identity its cloud or CI platform already gives it: Microsoft Entra ID or Entra Agent ID (v2.0 tokens), Google service accounts, Amazon EKS service-account tokens (IRSA), GitHub Actions OIDC tokens, or any OIDC issuer. Your organization trusts the issuer and binds an exact subject, plus optional claim conditions such as the repository and branch, to a registered agent with a scope ceiling and an optional pod or inbox restriction. The agent exchanges its token (OAuth 2.0 token exchange, RFC 8693) for a short-lived nofeb access token with no refresh token, usable on the API, MCP, JMAP and the realtime stream. No secret is stored: keys come from the issuer's published signing keys, and each external token is accepted once. Deleting the binding or issuer, or revoking the agent, ends its sessions at once; every exchange is audited, a dry run explains why a token would or would not be accepted, and mail the agent sends carries the external identity in its signed agent claims. Shipped
Agent identity and signed mail Register each agent with a name, a human sponsor and the keys it acts through. Its mail carries an agent header and a signature over the sender, recipients, subject and body that anyone can check against your organization's published keys or nofeb's verification call. Revoking an agent stops its keys from sending and marks its mail as revoked. Shipped
Append-only audit log Every change made through the API, MCP or the console, and every hold, denial, rejection and approval the server makes on its own, recorded with the actor, key, operation, target, outcome and request id. Query it with filters and cursors, or export it as JSON Lines. Shipped
Scoped API keys Keys bound to the organization, one pod or one inbox, holding only the scopes they are given. A key cannot mint a key wider than itself. Shipped
MCP sign-in with OAuth MCP clients connect by signing in instead of pasting a key: OAuth 2.1 with discovery, dynamic client registration, client ID metadata documents, PKCE, tokens bound to the MCP server, refresh-token rotation and immediate revocation. A person approves the scopes, and optionally one inbox, in the console, and can disconnect the app at any time. API keys keep working beside it. Shipped