---
title: "AAuth Agent Authorization | DreamFactory Docs"
source: "https://docs.dreamfactory.com/Security/aauth/overview"
canonical_url: "https://docs.dreamfactory.com/Security/aauth/overview"
converted_at: "2026-11-17T19:46:33.460Z"
format: "markdown"
converted_by: "html-to-md-ai"
---
AAuth lets AI agents call DreamFactory's REST APIs under `/api/v2` with signed HTTP requests instead of API keys. A person approves the agent, and what they approve is a **scope**, which is a DreamFactory **role**. The agent then gets exactly that role's access, acting for that person. AAuth is off until a sys admin turns it on. A request without AAuth headers gets the same status and body as before; while AAuth is on, DreamFactory's `400` and `401` "no credentials" answers also carry a discovery `Link` header.

LicensingAAuth requires a DreamFactory commercial license (Gold or Platinum).

This page explains what AAuth changes, how DreamFactory implements it and when to choose it over other authentication methods. To try it right away, follow the [quickstart](/Security/aauth/quickstart).

## Quick reference[​](#quick-reference)

ConceptValue**Admin UI path****Security > AAuth**, with the tabs Scopes, Person Servers, Agents, Activity, Grants and Try it**Where agents can use it**Every API under `/api/v2`. Not the MCP endpoints (`/mcp/...`). API keys and session tokens keep working alongside it.**Scope**An enabled DreamFactory role**Who can approve**On DreamFactory's own person server: a user who holds the scope's role, or a sys admin**Credentials**Nothing shared. Every request is signed (RFC 9421) with the agent's own key, and every token is bound to that key.**Token lifetime**Person and auth tokens last at most 1 hour. There are no refresh tokens.**Admin API**`/api/v2/system/aauth` (sys admins only)**Command line**`php artisan df:aauth status`, `php artisan df:aauth rotate-keys`, `php artisan df:aauth prune`**Protocol**draft-hardt-oauth-aauth-protocol-11 with draft-hardt-httpbis-signature-key-09 (see [Standards status](#standards-status))

## The problem with shared keys[​](#the-problem-with-shared-keys)

When an AI agent calls an API with an API key or a service account:

- The key is a bearer credential. Anyone who copies it, from a log, a configuration file or a chat transcript, can use it from anywhere until someone refreshes it.

- Nobody approves what the agent does on a person's behalf. The key's role decides, whoever the agent is working for.

- Logs show the key's app, not which agent acted for which person.

AAuth changes this:

- Each agent has its own verifiable identity, an agent id such as `aauth:[[email protected]](/cdn-cgi/l/email-protection)`, vouched for by its **agent provider**.

- A named person approves the agent on DreamFactory's consent page before it can act for them.

- Every request is signed with the agent's private key, and every token is bound to that key, so a token copied from a log is useless without the key.

- The **Activity** tab logs the agent, the person, the scope and the result of signed API requests, and keeps the rows for 30 days by default.

## Terms[​](#terms)

TermMeaningAgentSoftware that calls your APIs for a person, identified by an agent id such as `aauth:[[email protected]](/cdn-cgi/l/email-protection)`Agent providerAn https origin, such as `https://agents.example.com`, that vouches for its agents by publishing `/.well-known/aauth-agent.json` and their public keysPersonThe human the agent acts for, who approves itPerson serverWhere the person signs in and approves, and where the agent gets person and auth tokens. DreamFactory has one built in.ResourceThe API the agent calls: here DreamFactory's `/api/v2`Agent tokenIssued by the agent provider. Says which agent this is and which key it signs with.Person tokenIssued by the person server after the **identity step**: which person the agent acts forResource tokenIssued by DreamFactory in a challenge. Names the scope the request needs.Auth tokenIssued by the person server after the **scope consent**. Lets the agent call the API with that scope.ScopeA DreamFactory role that an admin offers to agents, such as `sales.read`

Every token is bound to the agent's key and lasts at most an hour (an agent token up to 24 hours).

## How it works in DreamFactory[​](#how-it-works-in-dreamfactory)

![Sequence diagram of the AAuth flow: the agent is challenged for a person token, the person signs in and continues, the agent is challenged for an auth token for scope sales.read, the person allows it, and the agent&#39;s signed request runs under that role.](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMTAwIiBoZWlnaHQ9IjEyNzAiIHZpZXdCb3g9IjAgMCAxMTAwIDEyNzAiIGZvbnQtZmFtaWx5PSItYXBwbGUtc3lzdGVtLCBCbGlua01hY1N5c3RlbUZvbnQsICdTZWdvZSBVSScsIFJvYm90bywgSGVsdmV0aWNhLCBBcmlhbCwgc2Fucy1zZXJpZiI+Cjx0aXRsZT5BQXV0aCBpbiBEcmVhbUZhY3Rvcnk6IGFuIGFnZW50IGdldHMgYSBwZXJzb24ncyBhcHByb3ZhbDwvdGl0bGU+CjxkZWZzPjxtYXJrZXIgaWQ9ImFyIiBtYXJrZXJXaWR0aD0iMTIiIG1hcmtlckhlaWdodD0iMTAiIHJlZlg9IjExIiByZWZZPSI1IiBvcmllbnQ9ImF1dG8iIG1hcmtlclVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+PHBhdGggZD0iTTAsMCBMMTIsNSBMMCwxMCB6IiBmaWxsPSIjMWYyOTM3Ii8+PC9tYXJrZXI+PC9kZWZzPgo8cmVjdCB4PSIxLjUiIHk9IjEuNSIgd2lkdGg9IjEwOTciIGhlaWdodD0iMTI2NyIgcng9IjE2IiByeT0iMTYiIGZpbGw9IiNmZmZmZmYiIHN0cm9rZT0iI2QxZDVkYiIgc3Ryb2tlLXdpZHRoPSIzIi8+Cjx0ZXh0IHg9IjU1MC4wIiB5PSI0NCIgZm9udC1zaXplPSIyNiIgZm9udC13ZWlnaHQ9ImJvbGQiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMxMTE4MjciPkFBdXRoIGluIERyZWFtRmFjdG9yeTogYW4gYWdlbnQgZ2V0cyBhIHBlcnNvbidzIGFwcHJvdmFsPC90ZXh0Pgo8cGF0aCBkPSJNNDk1LDkwIEw0OTUsODAgTDkzMCw4MCBMOTMwLDkwIiBmaWxsPSJub25lIiBzdHJva2U9IiM2YjcyODAiIHN0cm9rZS13aWR0aD0iMiIvPgo8dGV4dCB4PSI3MTIuNSIgeT0iNzIiIGZvbnQtc2l6ZT0iMTciIGZvbnQtd2VpZ2h0PSJib2xkIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMzc0MTUxIj5Jc3N1ZXIgaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb208L3RleHQ+CjxyZWN0IHg9Ijc1LjAiIHk9Ijk4IiB3aWR0aD0iMzEwIiBoZWlnaHQ9Ijc4IiByeD0iOCIgZmlsbD0iI2YzZjRmNiIgc3Ryb2tlPSIjMzc0MTUxIiBzdHJva2Utd2lkdGg9IjIiLz4KPHRleHQgeD0iMjMwIiB5PSIxMzIiIGZvbnQtc2l6ZT0iMTkiIGZvbnQtd2VpZ2h0PSJib2xkIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij5BZ2VudDwvdGV4dD4KPHRleHQgeD0iMjMwIiB5PSIxNTQiIGZvbnQtc2l6ZT0iMTYiIGZvbnQtd2VpZ2h0PSJub3JtYWwiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMzNzQxNTEiPmFhdXRoOnJlcG9ydHNAYWdlbnRzLmV4YW1wbGUuY29tPC90ZXh0Pgo8cmVjdCB4PSI0OTUuMCIgeT0iOTgiIHdpZHRoPSIyMTAiIGhlaWdodD0iNzgiIHJ4PSI4IiBmaWxsPSIjZTBlY2ZmIiBzdHJva2U9IiMzNzQxNTEiIHN0cm9rZS13aWR0aD0iMiIvPgo8dGV4dCB4PSI2MDAiIHk9IjEzMiIgZm9udC1zaXplPSIxOSIgZm9udC13ZWlnaHQ9ImJvbGQiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMxMTE4MjciPkRyZWFtRmFjdG9yeSBBUEk8L3RleHQ+Cjx0ZXh0IHg9IjYwMCIgeT0iMTU0IiBmb250LXNpemU9IjE2IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMzc0MTUxIj4vYXBpL3YyIChyZXNvdXJjZSk8L3RleHQ+CjxyZWN0IHg9IjczMC4wIiB5PSI5OCIgd2lkdGg9IjIwMCIgaGVpZ2h0PSI3OCIgcng9IjgiIGZpbGw9IiNlMGVjZmYiIHN0cm9rZT0iIzM3NDE1MSIgc3Ryb2tlLXdpZHRoPSIyIi8+Cjx0ZXh0IHg9IjgzMCIgeT0iMTIyIiBmb250LXNpemU9IjE5IiBmb250LXdlaWdodD0iYm9sZCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+RHJlYW1GYWN0b3J5PC90ZXh0Pgo8dGV4dCB4PSI4MzAiIHk9IjE0MyIgZm9udC1zaXplPSIxOSIgZm9udC13ZWlnaHQ9ImJvbGQiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMxMTE4MjciPnBlcnNvbiBzZXJ2ZXI8L3RleHQ+Cjx0ZXh0IHg9IjgzMCIgeT0iMTY0IiBmb250LXNpemU9IjE2IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMzc0MTUxIj4vYWF1dGg8L3RleHQ+CjxyZWN0IHg9IjkzNS4wIiB5PSI5OCIgd2lkdGg9IjE1MCIgaGVpZ2h0PSI3OCIgcng9IjgiIGZpbGw9IiNmM2Y0ZjYiIHN0cm9rZT0iIzM3NDE1MSIgc3Ryb2tlLXdpZHRoPSIyIi8+Cjx0ZXh0IHg9IjEwMTAiIHk9IjEyMiIgZm9udC1zaXplPSIxOSIgZm9udC13ZWlnaHQ9ImJvbGQiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMxMTE4MjciPlBlcnNvbjwvdGV4dD4KPHRleHQgeD0iMTAxMCIgeT0iMTQzIiBmb250LXNpemU9IjE2IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMzc0MTUxIj5Kb3JkYW4gTGVlLDwvdGV4dD4KPHRleHQgeD0iMTAxMCIgeT0iMTY0IiBmb250LXNpemU9IjE2IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMzc0MTUxIj5pbiBhIGJyb3dzZXI8L3RleHQ+CjxsaW5lIHgxPSIyMzAiIHkxPSIxNzYiIHgyPSIyMzAiIHkyPSIxMTEwIiBzdHJva2U9IiM5Y2EzYWYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWRhc2hhcnJheT0iNyw2Ii8+CjxsaW5lIHgxPSI2MDAiIHkxPSIxNzYiIHgyPSI2MDAiIHkyPSIxMTEwIiBzdHJva2U9IiM5Y2EzYWYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWRhc2hhcnJheT0iNyw2Ii8+CjxsaW5lIHgxPSI4MzAiIHkxPSIxNzYiIHgyPSI4MzAiIHkyPSIxMTEwIiBzdHJva2U9IiM5Y2EzYWYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWRhc2hhcnJheT0iNyw2Ii8+CjxsaW5lIHgxPSIxMDEwIiB5MT0iMTc2IiB4Mj0iMTAxMCIgeTI9IjExMTAiIHN0cm9rZT0iIzljYTNhZiIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtZGFzaGFycmF5PSI3LDYiLz4KPGxpbmUgeDE9IjIzMCIgeTE9IjIzOCIgeDI9IjU5NyIgeTI9IjIzOCIgc3Ryb2tlPSIjMWYyOTM3IiBzdHJva2Utd2lkdGg9IjIuNSIgbWFya2VyLWVuZD0idXJsKCNhcikiLz4KPHRleHQgeD0iNDE1LjAiIHk9IjIwNyIgZm9udC1zaXplPSIxNyIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+MS4gR0VUIC9hcGkvdjIvc2FsZXMvX3RhYmxlL29yZGVyczwvdGV4dD4KPHRleHQgeD0iNDE1LjAiIHk9IjIyOSIgZm9udC1zaXplPSIxNyIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+KHNpZ25lZCwgYWdlbnQgdG9rZW4pPC90ZXh0Pgo8cmVjdCB4PSIxNCIgeT0iMjU2IiB3aWR0aD0iMTk2IiBoZWlnaHQ9IjExMiIgcng9IjgiIGZpbGw9IiNmOWZhZmIiIHN0cm9rZT0iIzZiNzI4MCIgc3Ryb2tlLXdpZHRoPSIyIi8+Cjx0ZXh0IHg9IjExMi4wIiB5PSIyODIiIGZvbnQtc2l6ZT0iMTgiIGZvbnQtd2VpZ2h0PSJib2xkIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij5BZ2VudCBwcm92aWRlcjwvdGV4dD4KPHRleHQgeD0iMTEyLjAiIHk9IjMwNCIgZm9udC1zaXplPSIxNiIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzM3NDE1MSI+YWdlbnRzLmV4YW1wbGUuY29tPC90ZXh0Pgo8dGV4dCB4PSIxMTIuMCIgeT0iMzI2IiBmb250LXNpemU9IjE2IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMzc0MTUxIj5hYXV0aC1hZ2VudC5qc29uLDwvdGV4dD4KPHRleHQgeD0iMTEyLjAiIHk9IjM0OCIgZm9udC1zaXplPSIxNiIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzM3NDE1MSI+andrcy5qc29uPC90ZXh0Pgo8bGluZSB4MT0iNjAwIiB5MT0iMzMwLjAiIHgyPSIyMTMiIHkyPSIzMzAuMCIgc3Ryb2tlPSIjMWYyOTM3IiBzdHJva2Utd2lkdGg9IjMuNSIgc3Ryb2tlLWRhc2hhcnJheT0iMSw4IiBzdHJva2UtbGluZWNhcD0icm91bmQiIG1hcmtlci1lbmQ9InVybCgjYXIpIi8+Cjx0ZXh0IHg9IjQxNS4wIiB5PSIyOTkuMCIgZm9udC1zaXplPSIxNyIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzM3NDE1MSI+ZmV0Y2ggbWV0YWRhdGEgYW5kIGtleXM8L3RleHQ+Cjx0ZXh0IHg9IjQxNS4wIiB5PSIzMjEuMCIgZm9udC1zaXplPSIxNyIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzM3NDE1MSI+dG8gdmVyaWZ5IHRoZSBhZ2VudCB0b2tlbjwvdGV4dD4KPGxpbmUgeDE9IjYwMCIgeTE9IjQzMiIgeDI9IjIzMyIgeTI9IjQzMiIgc3Ryb2tlPSIjMWYyOTM3IiBzdHJva2Utd2lkdGg9IjIuNSIgc3Ryb2tlLWRhc2hhcnJheT0iMTAsNyIgbWFya2VyLWVuZD0idXJsKCNhcikiLz4KPHRleHQgeD0iNDE1LjAiIHk9IjQwMSIgZm9udC1zaXplPSIxNyIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+NDAxIEFBdXRoLVJlcXVpcmVtZW50OjwvdGV4dD4KPHRleHQgeD0iNDE1LjAiIHk9IjQyMyIgZm9udC1zaXplPSIxNyIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+cmVxdWlyZW1lbnQ9cGVyc29uLXRva2VuPC90ZXh0Pgo8bGluZSB4MT0iMjMwIiB5MT0iNDkwIiB4Mj0iODI3IiB5Mj0iNDkwIiBzdHJva2U9IiMxZjI5MzciIHN0cm9rZS13aWR0aD0iMi41IiBtYXJrZXItZW5kPSJ1cmwoI2FyKSIvPgo8dGV4dCB4PSI0MTUuMCIgeT0iNDgxIiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij4yLiBQT1NUIC9hYXV0aC9wZXJzb248L3RleHQ+CjxsaW5lIHgxPSI4MzAiIHkxPSI1NDAiIHgyPSIyMzMiIHkyPSI1NDAiIHN0cm9rZT0iIzFmMjkzNyIgc3Ryb2tlLXdpZHRoPSIyLjUiIHN0cm9rZS1kYXNoYXJyYXk9IjEwLDciIG1hcmtlci1lbmQ9InVybCgjYXIpIi8+Cjx0ZXh0IHg9IjQxNS4wIiB5PSI1MzEiIGZvbnQtc2l6ZT0iMTciIGZvbnQtd2VpZ2h0PSJub3JtYWwiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMxMTE4MjciPjIwMiwgY29kZSA3S1FNLTREMlA8L3RleHQ+CjxsaW5lIHgxPSIyMzAiIHkxPSI1OTAiIHgyPSIxMDA3IiB5Mj0iNTkwIiBzdHJva2U9IiMxZjI5MzciIHN0cm9rZS13aWR0aD0iMy41IiBzdHJva2UtZGFzaGFycmF5PSIxLDgiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgbWFya2VyLWVuZD0idXJsKCNhcikiLz4KPHRleHQgeD0iNDE1LjAiIHk9IjU4MSIgZm9udC1zaXplPSIxNyIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+My4gbGluayBhbmQgY29kZTwvdGV4dD4KPGxpbmUgeDE9IjEwMTAiIHkxPSI2NjIiIHgyPSI4MzMiIHkyPSI2NjIiIHN0cm9rZT0iIzFmMjkzNyIgc3Ryb2tlLXdpZHRoPSIyLjUiIG1hcmtlci1lbmQ9InVybCgjYXIpIi8+Cjx0ZXh0IHg9IjkyMC4wIiB5PSI2MzEiIGZvbnQtc2l6ZT0iMTciIGZvbnQtd2VpZ2h0PSJub3JtYWwiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMxMTE4MjciPlNpZ24gaW4sIENvbnRpbnVlPC90ZXh0Pgo8dGV4dCB4PSI5MjAuMCIgeT0iNjUzIiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij5hcyBKb3JkYW48L3RleHQ+CjxsaW5lIHgxPSIyMzAiIHkxPSI3MTIiIHgyPSI4MjciIHkyPSI3MTIiIHN0cm9rZT0iIzFmMjkzNyIgc3Ryb2tlLXdpZHRoPSIyLjUiIG1hcmtlci1lbmQ9InVybCgjYXIpIi8+Cjx0ZXh0IHg9IjQxNS4wIiB5PSI3MDMiIGZvbnQtc2l6ZT0iMTciIGZvbnQtd2VpZ2h0PSJub3JtYWwiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMxMTE4MjciPjQuIFBvbGwgL2FhdXRoL3BlbmRpbmcvLi4uPC90ZXh0Pgo8bGluZSB4MT0iODMwIiB5MT0iNzYyIiB4Mj0iMjMzIiB5Mj0iNzYyIiBzdHJva2U9IiMxZjI5MzciIHN0cm9rZS13aWR0aD0iMi41IiBzdHJva2UtZGFzaGFycmF5PSIxMCw3IiBtYXJrZXItZW5kPSJ1cmwoI2FyKSIvPgo8dGV4dCB4PSI0MTUuMCIgeT0iNzUzIiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij4yMDAgcGVyc29uIHRva2VuPC90ZXh0Pgo8bGluZSB4MT0iMjMwIiB5MT0iODEyIiB4Mj0iNTk3IiB5Mj0iODEyIiBzdHJva2U9IiMxZjI5MzciIHN0cm9rZS13aWR0aD0iMi41IiBtYXJrZXItZW5kPSJ1cmwoI2FyKSIvPgo8dGV4dCB4PSI0MTUuMCIgeT0iODAzIiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij41LiBHRVQgLi4uIChwZXJzb24gdG9rZW4pPC90ZXh0Pgo8bGluZSB4MT0iNjAwIiB5MT0iODg0IiB4Mj0iMjMzIiB5Mj0iODg0IiBzdHJva2U9IiMxZjI5MzciIHN0cm9rZS13aWR0aD0iMi41IiBzdHJva2UtZGFzaGFycmF5PSIxMCw3IiBtYXJrZXItZW5kPSJ1cmwoI2FyKSIvPgo8dGV4dCB4PSI0MTUuMCIgeT0iODUzIiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij40MDEgcmVxdWlyZW1lbnQ9YXV0aC10b2tlbjs8L3RleHQ+Cjx0ZXh0IHg9IjQxNS4wIiB5PSI4NzUiIGZvbnQtc2l6ZT0iMTciIGZvbnQtd2VpZ2h0PSJub3JtYWwiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMxMTE4MjciPnJlc291cmNlIHRva2VuIChzYWxlcy5yZWFkKTwvdGV4dD4KPGxpbmUgeDE9IjIzMCIgeTE9IjkzNCIgeDI9IjgyNyIgeTI9IjkzNCIgc3Ryb2tlPSIjMWYyOTM3IiBzdHJva2Utd2lkdGg9IjIuNSIgbWFya2VyLWVuZD0idXJsKCNhcikiLz4KPHRleHQgeD0iNDE1LjAiIHk9IjkyNSIgZm9udC1zaXplPSIxNyIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+Ni4gUE9TVCAvYWF1dGgvdG9rZW48L3RleHQ+CjxsaW5lIHgxPSIxMDEwIiB5MT0iOTYwIiB4Mj0iODMzIiB5Mj0iOTYwIiBzdHJva2U9IiMxZjI5MzciIHN0cm9rZS13aWR0aD0iMi41IiBtYXJrZXItZW5kPSJ1cmwoI2FyKSIvPgo8dGV4dCB4PSI5MjAuMCIgeT0iOTUxIiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij5BbGxvdyBzYWxlcy5yZWFkPC90ZXh0Pgo8bGluZSB4MT0iODMwIiB5MT0iMTAxMCIgeDI9IjIzMyIgeTI9IjEwMTAiIHN0cm9rZT0iIzFmMjkzNyIgc3Ryb2tlLXdpZHRoPSIyLjUiIHN0cm9rZS1kYXNoYXJyYXk9IjEwLDciIG1hcmtlci1lbmQ9InVybCgjYXIpIi8+Cjx0ZXh0IHg9IjQxNS4wIiB5PSIxMDAxIiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij4yMDAgYXV0aCB0b2tlbiAoYWZ0ZXIgcG9sbGluZyk8L3RleHQ+CjxsaW5lIHgxPSIyMzAiIHkxPSIxMDYwIiB4Mj0iNTk3IiB5Mj0iMTA2MCIgc3Ryb2tlPSIjMWYyOTM3IiBzdHJva2Utd2lkdGg9IjIuNSIgbWFya2VyLWVuZD0idXJsKCNhcikiLz4KPHRleHQgeD0iNDE1LjAiIHk9IjEwNTEiIGZvbnQtc2l6ZT0iMTciIGZvbnQtd2VpZ2h0PSJub3JtYWwiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMxMTE4MjciPjcuIEdFVCAuLi4gKGF1dGggdG9rZW4pPC90ZXh0Pgo8bGluZSB4MT0iNjAwIiB5MT0iMTExMCIgeDI9IjIzMyIgeTI9IjExMTAiIHN0cm9rZT0iIzFmMjkzNyIgc3Ryb2tlLXdpZHRoPSIyLjUiIHN0cm9rZS1kYXNoYXJyYXk9IjEwLDciIG1hcmtlci1lbmQ9InVybCgjYXIpIi8+Cjx0ZXh0IHg9IjQxNS4wIiB5PSIxMTAxIiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij4yMDAgQUF1dGgtU2NvcGU6IHNhbGVzLnJlYWQ8L3RleHQ+CjxyZWN0IHg9IjM4NSIgeT0iMTEyMiIgd2lkdGg9IjQzMCIgaGVpZ2h0PSIzOCIgcng9IjYiIGZpbGw9IiNmZmY3ZTYiIHN0cm9rZT0iI2Q5NzcwNiIgc3Ryb2tlLXdpZHRoPSIyIi8+Cjx0ZXh0IHg9IjYwMC4wIiB5PSIxMTQ5IiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjN2MyZDEyIj5SdW5zIGFzIHJvbGUgU2FsZXMgcmVhZCBmb3IgSm9yZGFuIExlZTwvdGV4dD4KPHJlY3QgeD0iMzAiIHk9IjExODIiIHdpZHRoPSIxMDQwIiBoZWlnaHQ9Ijc0IiByeD0iMTAiIGZpbGw9IiNmOWZhZmIiIHN0cm9rZT0iIzZiNzI4MCIgc3Ryb2tlLXdpZHRoPSIyIi8+Cjx0ZXh0IHg9IjU1MC4wIiB5PSIxMjEwIiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij5FdmVyeSByZXF1ZXN0IGlzIHNpZ25lZCB3aXRoIHRoZSBhZ2VudCdzIGtleSAoUkZDIDk0MjEpOyB0b2tlbnMgYXJlIGJvdW5kIHRvIHRoYXQga2V5LjwvdGV4dD4KPHRleHQgeD0iNTUwLjAiIHk9IjEyMzgiIGZvbnQtc2l6ZT0iMTYiIGZvbnQtd2VpZ2h0PSJub3JtYWwiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiM0YjU1NjMiPlNvbGlkOiByZXF1ZXN0LiBEYXNoZWQ6IHJlc3BvbnNlLiBEb3R0ZWQ6IHRoZSBhZ2VudCBzaG93cyB0aGUgcGVyc29uIGEgbGluaywgb3IgYSBkaXNjb3ZlcnkgZmV0Y2guPC90ZXh0Pgo8L3N2Zz4K)

1. The agent calls an API, for example `GET /api/v2/sales/_table/orders`, signed with its **agent token**. DreamFactory verifies the agent against its agent provider's published metadata and keys, and answers `401` with `AAuth-Requirement: requirement=person-token`.

2. The agent asks DreamFactory's **person server** for a **person token** (`POST /aauth/person`). The answer is `202` with a link and a code, such as `7KQM-4D2P`.

3. The agent gives the link to the person. The person opens it, signs in, and clicks **Continue as** with their first name (for example **Continue as Jordan**) to confirm that the agent acts for them. This is the **identity step**.

4. The agent polls the pending request and receives the person token.

5. The agent calls the API again, signed with the person token. DreamFactory works out which scope the request needs and answers `401` with `requirement=auth-token` and a **resource token** that names the scope, here `sales.read`.

6. The agent asks the person server for an **auth token** (`POST /aauth/token`). The person clicks **Allow** for the scope on the consent card (the **scope consent**), and the agent polls until it receives the auth token. If the person ticked **Always allow** earlier for this agent and every scope it now asks for, the person server returns the auth token at once, without a consent page.

7. The agent calls the API with the auth token. DreamFactory runs the request under the scope's role and returns the response with the header `AAuth-Scope: sales.read`.

The agent then reuses its tokens until they expire and signs every request afresh. Each request and response, header by header, is in [The AAuth HTTP Exchange](/Security/aauth/http-exchange).

You can watch the whole exchange in the admin app: **Try it** runs it with a built-in agent and draws every step.

![A completed Try it run drawn as a sequence across Agent, API and Person Server, ending with the Response card: status 200 and the JSON list of orders](/assets/images/try-it-result-feb481638832bc82b616febdd431da9e.png)

### One origin, three protocol roles[​](#one-origin-three-protocol-roles)

In AAuth terms, DreamFactory plays three parts. Each publishes a metadata document:

Protocol rolePublished atWhat it doesResource`/.well-known/aauth-resource.json`Verifies signed `/api/v2` calls, sends challenges in the `AAuth-Requirement` header, and issues resource tokensPerson server`/.well-known/aauth-person.json`People sign in (with a DreamFactory account, an LDAP or Active Directory account, or single sign-on) and approve agents at `/aauth/interact`Agent provider`/.well-known/aauth-agent.json`Identity of the built-in Try it agent only. Your own agents use their own agent provider.

All three live on one https origin, the **issuer**, which you set with `DF_AAUTH_ISSUER`, for example `https://api.example.com`. If `DF_AAUTH_ISSUER` is not set, DreamFactory uses the origin of `APP_URL` when that is https. DreamFactory can also trust external person servers, so that agents approved in your organization's own person server can call it. See [Person Servers](/Security/aauth/admin-guide#person-servers).

### Scopes are roles[​](#scopes-are-roles)

AAuth adds no new permission model:

- A sys admin enables a role as a scope, and gives it a name such as `sales.read` and a description that people read when they approve, such as "Read customers and orders".

- For each request, DreamFactory asks for the least privileged enabled scope that allows it ([How DreamFactory picks a scope](/Security/aauth/admin-guide#how-dreamfactory-picks-a-scope)). Agents do not need to know your roles: the challenge tells them which scope to ask for.

- The request runs with exactly that role, so the role's service access, filters, lookups, event scripts and rate limits apply as they would for an API key with that role.

- When the approval came from DreamFactory's own person server, the approving person's DreamFactory user is attached to the session too, always without sys admin rights, so lookups, per-user limits and scripts see that person.

- People can grant only roles they hold. Sys admins can grant any enabled scope. Whoever approves, the agent never gets sys admin rights.

## What agents can and cannot do[​](#what-agents-can-and-cannot-do)

Agents can:

- Call any `/api/v2` API that their scope's role allows.

- Appear under **Security > AAuth > Agents** on their first signed request. There is no registration step.

- Reuse their person and auth tokens for up to an hour.

- Skip the scope consent when the person ticked **Always allow** for that agent and those scopes earlier.

Agents cannot:

- Use AAuth on the MCP endpoints. MCP clients keep using OAuth, or an API key where the MCP service allows it ([API Key Authentication for MCP](/AI/mcp-api-key-auth)).

- Act without a person on DreamFactory's own person server. df-aauth 0.1.0 implements the three-party mode only, so there is no equivalent of OAuth's `client_credentials`. An external person server that you trust decides for itself how it issues tokens.

- Keep working past the person token's lifetime without the person. A person token lasts at most an hour, no auth token outlives the person token behind it, and every new person token needs the person to open a link and click **Continue as** again; **Always allow** skips only the scope consent. Plan for one person interaction per hour of continuous work.

- Get more access than the approving person could grant. On DreamFactory's own person server, a person grants only roles they hold, and this is checked again on every request.

## Choosing an authentication method[​](#choosing-an-authentication-method)

MethodWho is identifiedA person approves the callerIf the credential is copiedUse it forAAuthThe agent and the person it acts forYes, per agent and scopeUseless without the agent's private keyAI agents acting for identifiable people[API key](/api-generation-and-connections/api-keys) (app)The appNoWorks for anyone until the key is refreshedUnattended services, scripts and integrationsUser session tokenA signed-in personThe person signs in themselvesWorks until it expiresApps a person uses directly[Login services](/Security/authenticating-your-apis) (OAuth, OpenID Connect, SAML, LDAP)A person, through your identity providerThe person signs inAs for a session tokenPeople signing in to DreamFactory; also usable to [approve AAuth agents](/Security/aauth/sso-approval)[MCP server](/AI/mcp-server)An OAuth user, or an API key when the MCP service allows itWith OAuth, the person signs inWorks until the OAuth token expires or the key is refreshedMCP clients such as desktop assistants[Agents service](/AI/agents)An agent record with its own API keyAn admin approves access requestsAs for an API keyAn agent registry and capability routing

Choose AAuth when an agent acts for people and you want their approval, and an Activity log of which agent acted for whom. Keep API keys for unattended jobs, where no person is available to approve.

## Requirements at a glance[​](#requirements-at-a-glance)

RequirementDetailDreamFactory7.7.1 or later 7.xLicenseAAuth requires a DreamFactory commercial license (Gold or Platinum).Package`dreamfactory/df-aauth` installed, with its tables created (`php artisan migrate`)PHP8.3 or later with the `sodium`, `openssl`, `curl`, `json` and `mbstring` extensionsIssuerOne https origin on port 443 that agents and approvers reach, such as `https://api.example.com`. It can be public or internal. See [Choose the issuer](/Security/aauth/install#choose-the-issuer).Outbound httpsDreamFactory fetches the metadata and keys of the agent providers your agents use, on public addresses unless you admit internal ones ([Private networks and custom CAs](/Security/aauth/install#private-networks-and-custom-cas))ClocksBy default, signatures are accepted within 60 seconds of DreamFactory's clock. Run NTP on DreamFactory and agent hosts.Several DreamFactory nodesA shared Redis or Memcached cache and shared consent sessions ([Several DreamFactory nodes](/Security/aauth/operations#several-dreamfactory-nodes))AgentCode you control that signs its requests: the `aauth` command, the Node or Python client that ships in `vendor/dreamfactory/df-aauth`, or any client that implements the drafts. Assistants that only speak MCP, such as desktop assistants, can't use AAuth; they keep using OAuth or API keys. See [Building an Agent with the AAuth Clients](/Security/aauth/build-an-agent).Agent providerAn https origin you control that serves `/.well-known/aauth-agent.json` and a key set (JWKS). A static host is enough.ApproverA person the agent can send a link to, at least once an hour while it works, who holds the role behind each scope the agent needs, or a sys admin

Installation and every setting are in [Installing and Configuring AAuth](/Security/aauth/install).

## Standards status[​](#standards-status)

noteAAuth is defined by individual IETF Internet-Drafts, draft-hardt-oauth-aauth-protocol-11 and draft-hardt-httpbis-signature-key-09, not by finished standards. Later revisions of the drafts may change the protocol. DreamFactory implements the three-party person-server ("PS") authorization mode of these revisions. Requests are signed with [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421) HTTP message signatures, request bodies are covered with an [RFC 9530](https://www.rfc-editor.org/rfc/rfc9530) `Content-Digest`, and keys are Ed25519 or ES256. An agent that follows the drafts works with DreamFactory without DreamFactory-specific code.

Not supported in df-aauth 0.1.0: access servers, missions, sub-agents, call chaining, the revocation endpoint and multipart bodies. See [Out of scope in 0.1.0](/Security/aauth/security-model#out-of-scope-in-010).

## Next steps[​](#next-steps)

**DreamFactory admins:**

- **[Installing and Configuring AAuth](/Security/aauth/install)**: install the package, put a TLS reverse proxy in front of DreamFactory, and set the issuer

- **[Quickstart: Approve Your First Agent Call](/Security/aauth/quickstart)**: switch AAuth on and approve the built-in Try it agent

- **[Managing AAuth](/Security/aauth/admin-guide)**: every tab of Security > AAuth, who can approve what, and how to respond to an incident

- **[Approving Agents with Company Sign-In](/Security/aauth/sso-approval)**: let approvers sign in with LDAP, Active Directory or single sign-on

**Agent developers:**

- **[Building an Agent with the AAuth Clients](/Security/aauth/build-an-agent)**: give your own agent an identity and call DreamFactory from the command line, Node or Python

- **[The AAuth HTTP Exchange](/Security/aauth/http-exchange)**: the exact requests and responses, for writing a client in any language

- **[AAuth for OAuth Developers](/Security/aauth/oauth-mapping)**: how OAuth 2.0 and OpenID Connect concepts map to AAuth

**Security reviewers and operators:**

- **[AAuth Security Model](/Security/aauth/security-model)**: what DreamFactory verifies on every request, what it records, and what is left to you

- **[Operating AAuth in Production](/Security/aauth/operations)**: signing keys, backups, several nodes, monitoring and upgrades

- **[Troubleshooting AAuth](/Security/aauth/troubleshooting)**: every error an agent, approver or admin can see, and how to fix it