---
title: "The AAuth HTTP Exchange | DreamFactory Docs"
source: "https://docs.dreamfactory.com/Security/aauth/http-exchange"
canonical_url: "https://docs.dreamfactory.com/Security/aauth/http-exchange"
converted_at: "2026-11-17T19:46:34.423Z"
format: "markdown"
converted_by: "html-to-md-ai"
---
This page specifies every request an agent sends to DreamFactory under AAuth, and every answer it gets back. It is for developers who write their own AAuth client, in any language, instead of using the Node and Python clients that ship with df-aauth (see [Building an Agent with the AAuth Clients](/Security/aauth/build-an-agent)). DreamFactory implements the three-party person-server ("PS") authorization mode of draft-hardt-oauth-aauth-protocol-11, with draft-hardt-httpbis-signature-key-09 for the `Signature-Key` header (see [Standards status](/Security/aauth/overview#standards-status)). A client that follows those drafts needs no DreamFactory-specific code.

The examples use these names:

- DreamFactory, as resource and person server (the issuer): `https://api.example.com`

- Your agent provider: `https://agents.example.com`

- Your agent's id: `aauth:[[email protected]](/cdn-cgi/l/email-protection)`

Tokens, digests and signatures are shortened in the samples (`eyJ...`, `<agent token>`). Codes such as `7KQM-4D2P` are illustrative.

![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)

## What an agent needs[​](#what-an-agent-needs)

1. **A request key.** An Ed25519 key pair, or an ECDSA P-256 key pair for ES256. The private key never leaves the agent; every request is signed with it. Its public JWK must carry `alg`, either `"Ed25519"` or `"ES256"`. DreamFactory refuses the generic `"EdDSA"`.

2. **An agent provider.** An https origin you control that vouches for your agents. It serves `https://agents.example.com/.well-known/aauth-agent.json`:

```
{  "issuer": "https://agents.example.com",  "jwks_uri": "https://agents.example.com/jwks.json",  "name": "Reports agent",  "callback_endpoint": "https://agents.example.com/callback"}
```

`issuer` must equal the origin byte for byte. `name` is what people see on the consent page; it is self-asserted, so DreamFactory also shows the agent id. `callback_endpoint` is optional: an https URL the person's browser returns to after approving. The JWKS (`{"keys": [...]}`) holds the public keys that sign agent tokens. DreamFactory uses the key whose `kid` equals the `kid` in the agent token's header (a token without `kid` works only when the JWKS holds exactly one key); that key needs `alg`, `Ed25519` or `ES256`, equal to the token header's `alg`. DreamFactory must reach both documents over https on a public address, or on one the DreamFactory admin admitted (see [Private networks and custom CAs](/Security/aauth/install#private-networks-and-custom-cas)).

3. **An agent token.** A JWT with `typ` `aa-agent+jwt`, signed by the agent provider's key, that binds the agent id to the request key:

```
header  {"alg": "Ed25519", "typ": "aa-agent+jwt", "kid": "<provider key id>"}payload {  "iss": "https://agents.example.com",  "dwk": "aauth-agent.json",  "sub": "aauth:[email protected]",  "cnf": {"jwk": {"kty": "OKP", "crv": "Ed25519", "x": "<request public key>", "alg": "Ed25519"}},  "ps": "https://api.example.com",  "jti": "<random>",  "iat": 1794312000,  "exp": 1794315600}
```

`dwk` names the well-known document, `aauth-agent.json`, that DreamFactory reads at the `iss` origin to find the issuer's keys. The agent id is `aauth:<name>@<agent provider host>`, with letters, digits and `. _ + -` before the `@`. DreamFactory's person server refuses an agent token whose `sub` has another form (`401 invalid_jwt`). It checks the form only: df-aauth 0.1.0 does not check that the host after the `@` is the host of the agent provider in `iss`, so use your own provider's host as the protocol intends. `ps`, the person server the agent uses, is optional. The protocol caps `exp` at 24 hours after `iat`, and DreamFactory refuses an `iat` more than 60 seconds in the future.

4. **A person server the DreamFactory admin trusts.** Usually that is DreamFactory itself: `https://api.example.com/.well-known/aauth-person.json`. It can also be your organization's own person server, once an admin trusts it (see [What changes with an external person server](/Security/aauth/admin-guide#what-changes-with-an-external-person-server)).

5. **The person** the agent acts for: on DreamFactory's person server, someone with a DreamFactory account who holds the role behind the scope the agent needs.

There is no client registration. DreamFactory lists the agent under **Security > AAuth > Agents** on its first signed request, to `/api/v2`, to `/aauth/authorize` or to DreamFactory's person server.

## Endpoints[​](#endpoints)

Everything is on the issuer origin. Everything except `/api/v2` answers `404` while AAuth is off, and the person server endpoints also while DreamFactory's own person server is off: the JSON endpoints with `not_found`, the consent page and the grants page with the page "Agent sign-in is not available." A known `/aauth` path called with the wrong method answers `405 method_not_allowed` with an `Allow` header, even while AAuth is off.

EndpointSigned withPurpose`GET /.well-known/aauth-resource.json`Not signedResource metadata`GET /.well-known/aauth-person.json`Not signedPerson server metadata`GET /.well-known/aauth-agent.json`Not signedMetadata of the built-in Try it agent's provider`GET /aauth/jwks/resource.json`, `person.json`, `agent.json`Not signedPublic keysAny `/api/v2/...`Agent, person or auth tokenThe APIs`POST /aauth/authorize`Person or auth tokenA resource token for named scopes`POST /aauth/person`Agent tokenPerson token request`POST /aauth/token`Agent tokenAuth token request`GET /aauth/pending/{id}`Agent token, same key as the requestPoll a pending request`DELETE /aauth/pending/{id}`Agent token, same key as the requestCancel a pending request`/aauth/interact`Not signed (the person's browser)Consent pages`/aauth/grants`Not signed (the person's browser)The signed-in person's standing grants

The metadata, JWKS, authorization and person server endpoints answer `OPTIONS` and send `Access-Control-Allow-Origin: *`, so a browser-based agent can call them. They allow the request headers `Content-Type`, `Content-Digest`, `Signature`, `Signature-Input`, `Signature-Key`, `Prefer` and `AAuth-Capabilities`, and expose `AAuth-Requirement`, `Signature-Error`, `Accept-Signature-Scheme`, `Accept-Signature-Alg`, `Location` and `Retry-After`.

For `/api/v2` calls from a browser, DreamFactory's own CORS configuration applies (see [CORS and SSL Configuration](/system-settings/config/cors-and-ssl)). Add an entry for the agent's origin with:

- **Methods**: the methods the agent uses;

- **Headers**: `Signature`, `Signature-Input`, `Signature-Key`, `Content-Digest` and `Content-Type`, plus any headers of your own;

- **Exposed Headers**: `AAuth-Requirement`, `Signature-Error`, `AAuth-Scope`, `Location` and `Retry-After`.

DreamFactory also adds the AAuth headers in these lists (all but `Content-Type`) to whichever entry matches a request, so an entry for the agent's origin that lists only `Content-Type` and your own headers works as well. Without a matching entry, `/api/v2` answers carry no CORS headers, and the browser blocks the agent's calls.

## Signing requests[​](#signing-requests)

Every request to DreamFactory except the metadata and JWKS fetches is an RFC 9421 HTTP message signature with the label `sig`. The `Signature-Key` header carries one of the agent's tokens:

```
Signature-Key: sig=jwt;jwt="<agent token | person token | auth token>"Signature-Input: sig=("@method" "@authority" "@path" "signature-key" "@query");created=1794312000Signature: sig=:<standard base64 of the raw signature bytes>:
```

RuleDetail`Signature-Key``sig=jwt;jwt="<token>"`. Only the `jwt` scheme is accepted; any other gets `unsupported_scheme` with `Accept-Signature-Scheme: jwt`.Covered componentsAlways `@method`, `@authority`, `@path` and `signature-key`. With a body, also `content-type` and `content-digest`. On `/api/v2` and `/aauth/authorize`, also `@query` when the URL has a query string. The resource metadata lists the optional ones in `additional_signature_components`. A missing component gets `invalid_input` with `required_input=(...)` in `Signature-Error`. Cover each component once, in lowercase, without component parameters.`@authority`The issuer host, `api.example.com`: lowercase, no port. DreamFactory takes the value from the `Host` header it receives. A request whose `Host` is not the issuer host gets `invalid_signature` "Use [https://api.example.com](https://api.example.com)"; a signature over another `@authority` value gets "HTTP message signature is invalid".`@path`, `@query`Exactly as sent on the wire: the raw, still-encoded path, and `?` followed by the raw query. Covering `@query` on a URL without a query signs `?`.`created`Current Unix time, as an integer. Accepted within the signature window of the server clock: 60 seconds by default, published as `signature_window` in the resource metadata. More than the window in the past gets `invalid_signature`; more than the window in the future gets `clock_skew`. `expires` is optional and honored. DreamFactory ignores `alg` and `keyid`; the key comes from the token's `cnf.jwk`.Signature bytesThe request key's algorithm. Ed25519: the 64-byte signature. ES256: raw `r‖s` (64 bytes), not DER.`Content-Digest``sha-256=:<standard base64 of SHA-256(body)>:` over the exact body bytes (RFC 9530). DreamFactory also accepts `sha-512`.ReplaysA signed request with any method other than GET or HEAD is accepted once. DreamFactory remembers what was signed, the request key and the signature base, not the signature bytes, so another signature over the same base (such as the second valid form of an ES256 signature) is a replay too. Two identical requests signed with the same token within the same second have the same base, so the second is refused. Sign each request afresh.Not allowed on `/api/v2`Method overrides (`X-HTTP-Method`, `X-HTTP-Method-Override`, `X-Method-Override`, or anything else that changes the method), `multipart/form-data` bodies (send JSON), and a DreamFactory API key or session token in the same request. Each gets `400 invalid_request`.

The signature base for the request above, a `GET` of `/api/v2/sales/_table/orders?limit=5`:

```
"@method": GET"@authority": api.example.com"@path": /api/v2/sales/_table/orders"signature-key": sig=jwt;jwt="eyJ...""@query": ?limit=5"@signature-params": ("@method" "@authority" "@path" "signature-key" "@query");created=1794312000
```

The lines follow the order of `Signature-Input`, joined with `\n`, with no trailing newline. You choose the order; DreamFactory rebuilds the base in the order you sent.

Sign exactly what goes on the wireSign the raw, still-encoded path and query that your HTTP library sends. A library that re-encodes, normalizes or reorders the URL after you sign it breaks verification, and the request fails with "HTTP message signature is invalid". The same happens when a reverse proxy rewrites the path, the query or the `Host` header, or changes the body.

## The flow, request by request[​](#the-flow-request-by-request)

Every request in this section except the metadata fetch is signed. `Signature-Input` and `Signature` are shown only in step 2. Error bodies are `application/problem+json` with the members `error` and `detail`; signature and token errors also carry `type` (`urn:ietf:params:sig-error:<code>`) and a `Signature-Error` header.

### 0. Discover[​](#0-discover)

```
GET /.well-known/aauth-resource.json HTTP/1.1Host: api.example.comHTTP/1.1 200 OKContent-Type: application/jsonCache-Control: max-age=60, publicAccess-Control-Allow-Origin: *{"issuer":"https://api.example.com", "jwks_uri":"https://api.example.com/aauth/jwks/resource.json", "name":"DreamFactory", "access_mode":"auth-token", "authorization_endpoint":"https://api.example.com/aauth/authorize", "scope_descriptions":{"sales.read":"Read customers and orders","sales.refund":"Update order status"}, "signature_window":60, "additional_signature_components":["@query","content-type","content-digest"]}
```

Check that `issuer` equals the origin you fetched. `scope_descriptions` lists the enabled scopes with the descriptions people see.

While AAuth is on, DreamFactory's `400` or `401` answer to an API request that carries neither AAuth headers nor DreamFactory credentials also points here, without changing its status or body: `Link: <https://api.example.com/.well-known/aauth-resource.json>; rel="aauth-resource"`. A `401` answer also carries `AAuth-Requirement: requirement=agent-token`.

The person server's document is `/.well-known/aauth-person.json`:

```
{  "issuer": "https://api.example.com",  "jwks_uri": "https://api.example.com/aauth/jwks/person.json",  "person_token_endpoint": "https://api.example.com/aauth/person",  "auth_token_endpoint": "https://api.example.com/aauth/token",  "scopes_supported": ["profile", "email"],  "claims_supported": ["sub", "name", "email"],  "name": "DreamFactory",  "accept_signature_algs": ["Ed25519", "ES256"]}
```

### 1. Call with the agent token[​](#1-call-with-the-agent-token)

```
GET /api/v2/sales/_table/orders?limit=5 HTTP/1.1Host: api.example.comSignature-Key: sig=jwt;jwt="<agent token>"HTTP/1.1 401 UnauthorizedContent-Type: application/problem+jsonAAuth-Requirement: requirement=person-tokenCache-Control: no-store{"error":"person_token_required","detail":"Get a person token from your person server and sign with it."}
```

DreamFactory fetched your agent provider's metadata and JWKS (or took them from its cache), verified the agent token and the signature, and recorded the agent. An agent token alone never reaches an API: DreamFactory needs to know which person the agent acts for.

### 2. Ask for a person token[​](#2-ask-for-a-person-token)

```
POST /aauth/person HTTP/1.1Host: api.example.comContent-Type: application/jsonContent-Digest: sha-256=:<digest of the body>:Signature-Key: sig=jwt;jwt="<agent token>"Signature-Input: sig=("@method" "@authority" "@path" "signature-key" "content-type" "content-digest");created=1794312001Signature: sig=:<signature>:{"resource":"https://api.example.com","capabilities":["interaction"],"justification":"Weekly sales report"}HTTP/1.1 202 AcceptedContent-Type: application/jsonLocation: https://api.example.com/aauth/pending/Xq3...Retry-After: 2Cache-Control: no-storeAAuth-Requirement: requirement=interaction; url="https://api.example.com/aauth/interact"; code="7KQM-4D2P"{"status":"pending","code":"7KQM-4D2P"}
```

Body memberRule`resource`The resource's server identifier: an https origin. Otherwise `400 invalid_request` "resource must be a server identifier (https origin)."`capabilities`Must include `"interaction"`: this person server always has to reach the person. Otherwise `403 user_unreachable`.`justification`Optional. Shown to the person as a quote. Longer text is cut at 1000 characters.`mission_s256`Not supported: `400 invalid_request`.

The person server also checks that the agent token's `sub` is an agent id, and otherwise answers `401 invalid_jwt` "The agent token sub is not an agent identifier (aauth:name@domain)." It refuses sub-agent tokens. It also limits pending requests: at most 30 new ones per agent and 60 per client address each minute, and 20 waiting at once per agent. Over a limit it answers `429 rate_limited` with `Retry-After: 60`. A person token request always needs the person; nothing answers it at once.

### 3. Send the person to the consent page[​](#3-send-the-person-to-the-consent-page)

Show or open `https://api.example.com/aauth/interact?code=7KQM-4D2P`: the `url` and `code` from `AAuth-Requirement`. The person can also open `https://api.example.com/aauth/interact` and type the code. The first browser that acts on a code (signs in, starts single sign-on, presses any button on the card, or types the code) owns the request and its outcome; every other browser then gets "This code was already used in another browser". Opening the link claims nothing and does not change the request, so chat link previews and mail link scanners that fetch it first do no harm.

Show the link to the person onlyUntil the person acts, anyone who has the link or the code can act first: deny the request, or, on a person token request, sign in with their own account and become the person your agent acts for. Show the link and the code to the person you expect to approve, never in a shared channel.

If your agent provider publishes a `callback_endpoint`, you may append `&callback=` and that URL, URL-encoded. DreamFactory uses it only when its scheme, host and path match `callback_endpoint` (a query is allowed), and it must be https. The browser then goes there after the person decides: to the URL as given when approved, with `error=access_denied` added to its query when denied, and with `error=interaction_expired` when the request had expired. After the identity step, a browser with a callback shows "Approved" and goes there instead of waiting for the scope consent, so the person needs the link of the next request too. The callback carries no token: the result always comes from polling. Without `error`, it means only that the browser came back, not that your request was approved.

### 4. Poll[​](#4-poll)

Poll the `Location` URL, signed with the agent token and the same request key that created the request. Wait `Retry-After` seconds between polls.

```
GET /aauth/pending/Xq3... HTTP/1.1Host: api.example.comSignature-Key: sig=jwt;jwt="<agent token>"HTTP/1.1 202 AcceptedRetry-After: 2AAuth-Requirement: requirement=interaction; url="https://api.example.com/aauth/interact"; code="7KQM-4D2P"{"status":"interacting","code":"7KQM-4D2P"}
```

`status` is `pending` until a browser first acts on the consent page (signs in, starts single sign-on, presses any button on the card, or types the code, or, for a scope request, the page that approved the identity step moves on to it), and `interacting` after. Opening the link does not change it. Once the person signs in and chooses **Continue as**:

```
HTTP/1.1 200 OKContent-Type: application/jsonCache-Control: no-store{"person_token":"eyJ...","expires_in":3542}
```

Answer`error` and `detail`Means`202`Still waiting. Poll again after `Retry-After`.`200`The token. It is delivered once; later polls get `410`.`403``denied` "The person denied the request."The person said no`408``expired` "The request expired before the person answered."No answer within 10 minutes`410``invalid_code` "This pending request is finished."Already delivered, reported or cancelled, or ended by too many failed sign-ins`404``invalid_request` "Unknown pending request."Unknown id, or polled with a different key

`DELETE` on the same URL, signed the same way, cancels a waiting request and answers `204`. The person token (`typ` `aa-person+jwt`) has `iss` = the person server, `aud` = the resource, `sub` = a stable pseudonymous identifier for this person at this resource (the same for every agent), `cnf.jwk` = your request key, `jti`, `iat` and `exp`. Check `iss`, `aud` and `cnf.jwk` before you use it.

### 5. Call with the person token[​](#5-call-with-the-person-token)

```
GET /api/v2/sales/_table/orders?limit=5 HTTP/1.1Host: api.example.comSignature-Key: sig=jwt;jwt="<person token>"HTTP/1.1 401 UnauthorizedContent-Type: application/problem+jsonAAuth-Requirement: requirement=auth-token; resource-token="eyJ..."Cache-Control: no-store{"error":"auth_token_required","detail":"Ask your person server for an auth token for scope sales.read."}
```

DreamFactory picked the least privileged enabled scope that allows this request, `sales.read` (see [How DreamFactory picks a scope](/Security/aauth/admin-guide#how-dreamfactory-picks-a-scope)). When no enabled scope allows it, the answer is `403 insufficient_scope` "No scope allows GET sales/_table/orders" without `AAuth-Requirement`; asking again won't help.

The resource token (`typ` `aa-resource+jwt`, valid 5 minutes) is signed with the resource key and has these claims:

ClaimValue`iss`The resource, `https://api.example.com``aud`, `ps`The person server that issued your person token`sub`, `presented_jti`The `sub` and `jti` of the token you presented`agent_jkt`The RFC 7638 thumbprint of your request key`scope`The scope (or space-separated scopes) to ask for`jti`, `iat`, `exp`Its own id and times

Before you forward it, verify its signature against the resource's JWKS and check that `iss` is the resource you called, `agent_jkt` is your key's thumbprint, `aud` and `ps` are your person server, `sub` and `presented_jti` match the token you presented, and `exp` is in the future.

In the admin app, **Try it** shows the same exchange step by step. Expanding the `401` row shows the `AAuth-Requirement` header and the decoded resource token:

![The response part of an expanded Try it step: the 401 with the AAuth-Requirement header, and the decoded resource token asking for scope sales.read](/img/security/aauth/try-it-step-tokens.png)
Instead of this round trip, you can ask for a resource token up front. Sign the request with the person token (or a current auth token):

```
POST /aauth/authorize HTTP/1.1Host: api.example.comContent-Type: application/jsonContent-Digest: sha-256=:<digest of the body>:Signature-Key: sig=jwt;jwt="<person token>"{"scope":"sales.read"}HTTP/1.1 200 OKContent-Type: application/jsonCache-Control: no-store{"resource_token":"eyJ..."}
```

The resource token asks for exactly the scopes you name. When you sign with an auth token, name the scopes it already carries as well (`"sales.read sales.refund"`), or the new auth token carries only the new ones. `scope` is required (`400 invalid_request` "scope is required."). A scope that is not enabled, or that your person server may not vouch for, gets `400 invalid_scope` (`Unknown or unavailable scope: <scopes>`). Signed with an agent token, the endpoint answers `401 person_token_required` "Sign this request with a person token." A blocked agent gets `403 agent_blocked` here as on the APIs.

### 6. Ask for an auth token[​](#6-ask-for-an-auth-token)

Requests to the person server are always signed with the **agent** token. The person token goes in the body:

```
POST /aauth/token HTTP/1.1Host: api.example.comContent-Type: application/jsonContent-Digest: sha-256=:<digest of the body>:Signature-Key: sig=jwt;jwt="<agent token>"{"resource_token":"eyJ...","presented_token":"<person token>","justification":"Weekly sales report"}HTTP/1.1 202 AcceptedContent-Type: application/jsonLocation: https://api.example.com/aauth/pending/Bv8...Retry-After: 2Cache-Control: no-storeAAuth-Requirement: requirement=interaction; url="https://api.example.com/aauth/interact"; code="R9TW-2HXC"{"status":"pending","code":"R9TW-2HXC"}
```

The person server checks that the resource token is addressed to it, names it as `ps` and is bound to the key that signed this request, and that the presented token is one it issued, for the same resource, key, `sub` and `jti`. A resource token is used once. A retry with the same resource token and the same key, while the request is still waiting, returns the same pending request, so you can retry safely after a lost response.

What happens next:

- If the person gave this agent **Always allow** for every requested scope and still holds the roles behind them, the answer is `200 {"auth_token":"eyJ...","expires_in":...}` at once.

- Otherwise the person approves on the consent page, and you poll as in step 4 until `200 {"auth_token":"eyJ...","expires_in":...}`. When the person approved the identity step in the same browser, without a callback, the consent page waits up to 2 minutes for this request and moves on to it by itself. You can still show the new link and code.

- Only the person in the presented token can approve. Anyone else who signs in on the link is asked to "Sign in as the person this agent acts for."

The auth token (`typ` `aa-auth+jwt`) has `iss` and `ps` = the person server, `aud` = the resource, `sub`, `cnf.jwk` = your request key, and the granted `scope`. The person may grant fewer scopes than you asked for. Check that `iss` is the resource token's `aud`, `aud` is the resource, `cnf.jwk` is your key and `sub` matches the token you presented.

### 7. Call with the auth token[​](#7-call-with-the-auth-token)

```
GET /api/v2/sales/_table/orders?limit=5 HTTP/1.1Host: api.example.comSignature-Key: sig=jwt;jwt="<auth token>"HTTP/1.1 200 OKContent-Type: application/jsonAAuth-Scope: sales.read{"resource":[...]}
```

DreamFactory runs the request with the role behind the scope it used and names that scope in `AAuth-Scope`. When the token comes from DreamFactory's own person server, the request also runs as the person's DreamFactory user, never with sys admin rights, and DreamFactory checks on every request that the person is still active and still holds the role. Otherwise the answer is `403 denied` "The person this agent acts for is no longer active." or `403 insufficient_scope` "The person no longer holds the role behind scope sales.read."

Reuse the auth token for every request its scopes allow until it expires, and sign each request afresh.

## Step-up[  ​](#step-up)

When a request needs a scope that the auth token does not carry, DreamFactory challenges again and the agent asks for more:

![Sequence diagram of a step-up: a PATCH with a sales.read auth token is challenged for sales.refund, the person allows the added scope, and the PATCH succeeds under sales.refund.](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMTAwIiBoZWlnaHQ9IjExNTAiIHZpZXdCb3g9IjAgMCAxMTAwIDExNTAiIGZvbnQtZmFtaWx5PSItYXBwbGUtc3lzdGVtLCBCbGlua01hY1N5c3RlbUZvbnQsICdTZWdvZSBVSScsIFJvYm90bywgSGVsdmV0aWNhLCBBcmlhbCwgc2Fucy1zZXJpZiI+Cjx0aXRsZT5TdGVwLXVwOiBhc2tpbmcgZm9yIGEgc2Vjb25kIHNjb3BlPC90aXRsZT4KPGRlZnM+PG1hcmtlciBpZD0iYXIiIG1hcmtlcldpZHRoPSIxMiIgbWFya2VySGVpZ2h0PSIxMCIgcmVmWD0iMTEiIHJlZlk9IjUiIG9yaWVudD0iYXV0byIgbWFya2VyVW5pdHM9InVzZXJTcGFjZU9uVXNlIj48cGF0aCBkPSJNMCwwIEwxMiw1IEwwLDEwIHoiIGZpbGw9IiMxZjI5MzciLz48L21hcmtlcj48L2RlZnM+CjxyZWN0IHg9IjEuNSIgeT0iMS41IiB3aWR0aD0iMTA5NyIgaGVpZ2h0PSIxMTQ3IiByeD0iMTYiIHJ5PSIxNiIgZmlsbD0iI2ZmZmZmZiIgc3Ryb2tlPSIjZDFkNWRiIiBzdHJva2Utd2lkdGg9IjMiLz4KPHRleHQgeD0iNTUwLjAiIHk9IjQ0IiBmb250LXNpemU9IjI2IiBmb250LXdlaWdodD0iYm9sZCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+U3RlcC11cDogYXNraW5nIGZvciBhIHNlY29uZCBzY29wZTwvdGV4dD4KPHBhdGggZD0iTTQ5NSw5MCBMNDk1LDgwIEw5MzAsODAgTDkzMCw5MCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjNmI3MjgwIiBzdHJva2Utd2lkdGg9IjIiLz4KPHRleHQgeD0iNzEyLjUiIHk9IjcyIiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0iYm9sZCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzM3NDE1MSI+SXNzdWVyIGh0dHBzOi8vYXBpLmV4YW1wbGUuY29tPC90ZXh0Pgo8cmVjdCB4PSI3NS4wIiB5PSI5OCIgd2lkdGg9IjMxMCIgaGVpZ2h0PSI3OCIgcng9IjgiIGZpbGw9IiNmM2Y0ZjYiIHN0cm9rZT0iIzM3NDE1MSIgc3Ryb2tlLXdpZHRoPSIyIi8+Cjx0ZXh0IHg9IjIzMCIgeT0iMTMyIiBmb250LXNpemU9IjE5IiBmb250LXdlaWdodD0iYm9sZCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+QWdlbnQ8L3RleHQ+Cjx0ZXh0IHg9IjIzMCIgeT0iMTU0IiBmb250LXNpemU9IjE2IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMzc0MTUxIj5hYXV0aDpyZXBvcnRzQGFnZW50cy5leGFtcGxlLmNvbTwvdGV4dD4KPHJlY3QgeD0iNDk1LjAiIHk9Ijk4IiB3aWR0aD0iMjEwIiBoZWlnaHQ9Ijc4IiByeD0iOCIgZmlsbD0iI2UwZWNmZiIgc3Ryb2tlPSIjMzc0MTUxIiBzdHJva2Utd2lkdGg9IjIiLz4KPHRleHQgeD0iNjAwIiB5PSIxMzIiIGZvbnQtc2l6ZT0iMTkiIGZvbnQtd2VpZ2h0PSJib2xkIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij5EcmVhbUZhY3RvcnkgQVBJPC90ZXh0Pgo8dGV4dCB4PSI2MDAiIHk9IjE1NCIgZm9udC1zaXplPSIxNiIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzM3NDE1MSI+L2FwaS92MiAocmVzb3VyY2UpPC90ZXh0Pgo8cmVjdCB4PSI3MzAuMCIgeT0iOTgiIHdpZHRoPSIyMDAiIGhlaWdodD0iNzgiIHJ4PSI4IiBmaWxsPSIjZTBlY2ZmIiBzdHJva2U9IiMzNzQxNTEiIHN0cm9rZS13aWR0aD0iMiIvPgo8dGV4dCB4PSI4MzAiIHk9IjEyMiIgZm9udC1zaXplPSIxOSIgZm9udC13ZWlnaHQ9ImJvbGQiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMxMTE4MjciPkRyZWFtRmFjdG9yeTwvdGV4dD4KPHRleHQgeD0iODMwIiB5PSIxNDMiIGZvbnQtc2l6ZT0iMTkiIGZvbnQtd2VpZ2h0PSJib2xkIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij5wZXJzb24gc2VydmVyPC90ZXh0Pgo8dGV4dCB4PSI4MzAiIHk9IjE2NCIgZm9udC1zaXplPSIxNiIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzM3NDE1MSI+L2FhdXRoPC90ZXh0Pgo8cmVjdCB4PSI5MzUuMCIgeT0iOTgiIHdpZHRoPSIxNTAiIGhlaWdodD0iNzgiIHJ4PSI4IiBmaWxsPSIjZjNmNGY2IiBzdHJva2U9IiMzNzQxNTEiIHN0cm9rZS13aWR0aD0iMiIvPgo8dGV4dCB4PSIxMDEwIiB5PSIxMzIiIGZvbnQtc2l6ZT0iMTkiIGZvbnQtd2VpZ2h0PSJib2xkIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij5QZXJzb248L3RleHQ+Cjx0ZXh0IHg9IjEwMTAiIHk9IjE1NCIgZm9udC1zaXplPSIxNiIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzM3NDE1MSI+aW4gYSBicm93c2VyPC90ZXh0Pgo8bGluZSB4MT0iMjMwIiB5MT0iMTc2IiB4Mj0iMjMwIiB5Mj0iOTkwIiBzdHJva2U9IiM5Y2EzYWYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWRhc2hhcnJheT0iNyw2Ii8+CjxsaW5lIHgxPSI2MDAiIHkxPSIxNzYiIHgyPSI2MDAiIHkyPSI5OTAiIHN0cm9rZT0iIzljYTNhZiIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtZGFzaGFycmF5PSI3LDYiLz4KPGxpbmUgeDE9IjgzMCIgeTE9IjE3NiIgeDI9IjgzMCIgeTI9Ijk5MCIgc3Ryb2tlPSIjOWNhM2FmIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1kYXNoYXJyYXk9IjcsNiIvPgo8bGluZSB4MT0iMTAxMCIgeTE9IjE3NiIgeDI9IjEwMTAiIHkyPSI5OTAiIHN0cm9rZT0iIzljYTNhZiIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtZGFzaGFycmF5PSI3LDYiLz4KPHJlY3QgeD0iODAiIHk9IjE5MiIgd2lkdGg9IjMwMCIgaGVpZ2h0PSI2MCIgcng9IjYiIGZpbGw9IiNmZmY3ZTYiIHN0cm9rZT0iI2Q5NzcwNiIgc3Ryb2tlLXdpZHRoPSIyIi8+Cjx0ZXh0IHg9IjIzMC4wIiB5PSIyMTkiIGZvbnQtc2l6ZT0iMTciIGZvbnQtd2VpZ2h0PSJub3JtYWwiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiM3YzJkMTIiPmhvbGRzIGFuIGF1dGggdG9rZW4gZm9yPC90ZXh0Pgo8dGV4dCB4PSIyMzAuMCIgeT0iMjQxIiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjN2MyZDEyIj5zY29wZSBzYWxlcy5yZWFkPC90ZXh0Pgo8bGluZSB4MT0iMjMwIiB5MT0iMzE4IiB4Mj0iNTk3IiB5Mj0iMzE4IiBzdHJva2U9IiMxZjI5MzciIHN0cm9rZS13aWR0aD0iMi41IiBtYXJrZXItZW5kPSJ1cmwoI2FyKSIvPgo8dGV4dCB4PSI0MTUuMCIgeT0iMjg3IiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij5hLiBQQVRDSCAuLi4vX3RhYmxlL29yZGVycy81PC90ZXh0Pgo8dGV4dCB4PSI0MTUuMCIgeT0iMzA5IiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij4oYXV0aCB0b2tlbjogc2FsZXMucmVhZCk8L3RleHQ+CjxsaW5lIHgxPSI2MDAiIHkxPSI0MDgiIHgyPSIyMzMiIHkyPSI0MDgiIHN0cm9rZT0iIzFmMjkzNyIgc3Ryb2tlLXdpZHRoPSIyLjUiIHN0cm9rZS1kYXNoYXJyYXk9IjEwLDciIG1hcmtlci1lbmQ9InVybCgjYXIpIi8+Cjx0ZXh0IHg9IjQxNS4wIiB5PSIzNTUiIGZvbnQtc2l6ZT0iMTciIGZvbnQtd2VpZ2h0PSJub3JtYWwiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMxMTE4MjciPjQwMSBpbnN1ZmZpY2llbnRfc2NvcGUsPC90ZXh0Pgo8dGV4dCB4PSI0MTUuMCIgeT0iMzc3IiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij5yZXF1aXJlbWVudD1hdXRoLXRva2VuLDwvdGV4dD4KPHRleHQgeD0iNDE1LjAiIHk9IjM5OSIgZm9udC1zaXplPSIxNyIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+cmVzb3VyY2UgdG9rZW4gKHNhbGVzLnJlYWQgc2FsZXMucmVmdW5kKTwvdGV4dD4KPGxpbmUgeDE9IjIzMCIgeTE9IjQ4MCIgeDI9IjgyNyIgeTI9IjQ4MCIgc3Ryb2tlPSIjMWYyOTM3IiBzdHJva2Utd2lkdGg9IjIuNSIgbWFya2VyLWVuZD0idXJsKCNhcikiLz4KPHRleHQgeD0iNDE1LjAiIHk9IjQ0OSIgZm9udC1zaXplPSIxNyIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+Yi4gUE9TVCAvYWF1dGgvdG9rZW4sIHByZXNlbnRlZDwvdGV4dD4KPHRleHQgeD0iNDE1LjAiIHk9IjQ3MSIgZm9udC1zaXplPSIxNyIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+dG9rZW4gPSBjdXJyZW50IGF1dGggdG9rZW48L3RleHQ+CjxsaW5lIHgxPSI4MzAiIHkxPSI1MzAiIHgyPSIyMzMiIHkyPSI1MzAiIHN0cm9rZT0iIzFmMjkzNyIgc3Ryb2tlLXdpZHRoPSIyLjUiIHN0cm9rZS1kYXNoYXJyYXk9IjEwLDciIG1hcmtlci1lbmQ9InVybCgjYXIpIi8+Cjx0ZXh0IHg9IjQxNS4wIiB5PSI1MjEiIGZvbnQtc2l6ZT0iMTciIGZvbnQtd2VpZ2h0PSJub3JtYWwiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMxMTE4MjciPjIwMiwgY29kZSBNNFhELThQUVQ8L3RleHQ+CjxsaW5lIHgxPSIyMzAiIHkxPSI2MDIiIHgyPSIxMDA3IiB5Mj0iNjAyIiBzdHJva2U9IiMxZjI5MzciIHN0cm9rZS13aWR0aD0iMy41IiBzdHJva2UtZGFzaGFycmF5PSIxLDgiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgbWFya2VyLWVuZD0idXJsKCNhcikiLz4KPHRleHQgeD0iNDE1LjAiIHk9IjU3MSIgZm9udC1zaXplPSIxNyIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+Yy4gbGluayBhbmQgY29kZSAoYW4gb3BlbjwvdGV4dD4KPHRleHQgeD0iNDE1LjAiIHk9IjU5MyIgZm9udC1zaXplPSIxNyIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+Y29uc2VudCBwYWdlIG1vdmVzIG9uIGJ5IGl0c2VsZik8L3RleHQ+CjxsaW5lIHgxPSIxMDEwIiB5MT0iNjc0IiB4Mj0iODMzIiB5Mj0iNjc0IiBzdHJva2U9IiMxZjI5MzciIHN0cm9rZS13aWR0aD0iMi41IiBtYXJrZXItZW5kPSJ1cmwoI2FyKSIvPgo8dGV4dCB4PSI5MjAuMCIgeT0iNjQzIiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij5kLiBDb25zZW50IGNhcmQ6PC90ZXh0Pgo8dGV4dCB4PSI5MjAuMCIgeT0iNjY1IiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij5BbGxvdyBib3RoIHNjb3BlczwvdGV4dD4KPHJlY3QgeD0iNjQ1IiB5PSI2OTAiIHdpZHRoPSI0NDAiIGhlaWdodD0iODIiIHJ4PSI2IiBmaWxsPSIjZmZmN2U2IiBzdHJva2U9IiNkOTc3MDYiIHN0cm9rZS13aWR0aD0iMiIvPgo8dGV4dCB4PSI4NjUuMCIgeT0iNzE3IiBmb250LXNpemU9IjE2IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjN2MyZDEyIj5Kb3JkYW4gTGVlIGhvbGRzIGJvdGggcm9sZXM6IGNhbiBhbGxvdy48L3RleHQ+Cjx0ZXh0IHg9Ijg2NS4wIiB5PSI3MzkiIGZvbnQtc2l6ZT0iMTYiIGZvbnQtd2VpZ2h0PSJub3JtYWwiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiM3YzJkMTIiPlNhbSBQYXRlbCBsYWNrcyBTYWxlcyByZWZ1bmRzOjwvdGV4dD4KPHRleHQgeD0iODY1LjAiIHk9Ijc2MSIgZm9udC1zaXplPSIxNiIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzdjMmQxMiI+c2FsZXMucmVmdW5kIGxvY2tlZCwgQWxsb3cgZGlzYWJsZWQuPC90ZXh0Pgo8bGluZSB4MT0iODMwIiB5MT0iODYwIiB4Mj0iMjMzIiB5Mj0iODYwIiBzdHJva2U9IiMxZjI5MzciIHN0cm9rZS13aWR0aD0iMi41IiBzdHJva2UtZGFzaGFycmF5PSIxMCw3IiBtYXJrZXItZW5kPSJ1cmwoI2FyKSIvPgo8dGV4dCB4PSI0MTUuMCIgeT0iODI5IiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij5lLiAyMDAgYXV0aCB0b2tlbiBhZnRlciBwb2xsaW5nPC90ZXh0Pgo8dGV4dCB4PSI0MTUuMCIgeT0iODUxIiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij4oc2FsZXMucmVhZCBzYWxlcy5yZWZ1bmQpPC90ZXh0Pgo8bGluZSB4MT0iMjMwIiB5MT0iOTIwIiB4Mj0iNTk3IiB5Mj0iOTIwIiBzdHJva2U9IiMxZjI5MzciIHN0cm9rZS13aWR0aD0iMi41IiBtYXJrZXItZW5kPSJ1cmwoI2FyKSIvPgo8dGV4dCB4PSI0MTUuMCIgeT0iOTExIiBmb250LXNpemU9IjE3IiBmb250LXdlaWdodD0ibm9ybWFsIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmaWxsPSIjMTExODI3Ij5mLiBQQVRDSCBhZ2Fpbiwgc2lnbmVkIGFmcmVzaDwvdGV4dD4KPGxpbmUgeDE9IjYwMCIgeTE9Ijk3OCIgeDI9IjIzMyIgeTI9Ijk3OCIgc3Ryb2tlPSIjMWYyOTM3IiBzdHJva2Utd2lkdGg9IjIuNSIgc3Ryb2tlLWRhc2hhcnJheT0iMTAsNyIgbWFya2VyLWVuZD0idXJsKCNhcikiLz4KPHRleHQgeD0iNDE1LjAiIHk9Ijk2OSIgZm9udC1zaXplPSIxNyIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+MjAwIEFBdXRoLVNjb3BlOiBzYWxlcy5yZWZ1bmQ8L3RleHQ+CjxyZWN0IHg9IjMwIiB5PSIxMDEwIiB3aWR0aD0iMTA0MCIgaGVpZ2h0PSIxMjQiIHJ4PSIxMCIgZmlsbD0iI2Y5ZmFmYiIgc3Ryb2tlPSIjNmI3MjgwIiBzdHJva2Utd2lkdGg9IjIiLz4KPHRleHQgeD0iNTUwLjAiIHk9IjEwNDAiIGZvbnQtc2l6ZT0iMTciIGZvbnQtd2VpZ2h0PSJub3JtYWwiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMxMTE4MjciPkRyZWFtRmFjdG9yeSBhc2tzIGZvciB0aGUgbGVhc3QgcHJpdmlsZWdlZCBlbmFibGVkIHNjb3BlIHRoYXQgYWxsb3dzIHRoZSByZXF1ZXN0OjwvdGV4dD4KPHRleHQgeD0iNTUwLjAiIHk9IjEwNjQiIGZvbnQtc2l6ZT0iMTciIGZvbnQtd2VpZ2h0PSJub3JtYWwiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMxMTE4MjciPmZld2VzdCBhY2Nlc3Mgcm93cywgdGhlbiBmZXdlc3QgdmVyYnMsIHRoZW4gbG93ZXN0IHJvbGUgaWQuPC90ZXh0Pgo8dGV4dCB4PSI1NTAuMCIgeT0iMTA5NCIgZm9udC1zaXplPSIxNyIgZm9udC13ZWlnaHQ9Im5vcm1hbCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzExMTgyNyI+VGhlIG5ldyBhdXRoIHRva2VuIGV4cGlyZXMgd2hlbiB0aGUgb2xkIG9uZSB3b3VsZCBoYXZlLjwvdGV4dD4KPHRleHQgeD0iNTUwLjAiIHk9IjExMjAiIGZvbnQtc2l6ZT0iMTYiIGZvbnQtd2VpZ2h0PSJub3JtYWwiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiM0YjU1NjMiPlNvbGlkOiByZXF1ZXN0LiBEYXNoZWQ6IHJlc3BvbnNlLiBEb3R0ZWQ6IHRoZSBhZ2VudCBzaG93cyB0aGUgcGVyc29uIGEgbGluay48L3RleHQ+Cjwvc3ZnPgo=)

```
PATCH /api/v2/sales/_table/orders/5 HTTP/1.1Host: api.example.comContent-Type: application/jsonContent-Digest: sha-256=:<digest of the body>:Signature-Key: sig=jwt;jwt="<auth token with scope sales.read>"{"status":"refunded"}HTTP/1.1 401 UnauthorizedContent-Type: application/problem+jsonAAuth-Requirement: requirement=auth-token; resource-token="eyJ..."Cache-Control: no-store{"error":"insufficient_scope","detail":"Scope sales.refund is needed for PATCH sales/_table/orders/5."}
```

1. The new resource token asks for the scopes the auth token already has plus the new one: `sales.read sales.refund`.

2. Send it to `/aauth/token` as in step 6, with the current **auth token** as `presented_token`.

3. The consent page lists every requested scope, the ones already granted and the new one, each with its description. Scopes the person can grant are ticked. **Allow** needs at least one new scope ticked; otherwise the page says "Select at least one new scope to allow, or deny." A scope whose role the person doesn't hold is locked with "You don't have this role", and when no new scope is grantable, **Allow** is disabled.

4. Poll as in step 4. The new auth token carries the scopes the person allowed. It expires when the presented auth token would have, because an auth token never outlives the token presented to get it.

5. Send the PATCH again, signed afresh with the new auth token. The answer carries `AAuth-Scope: sales.refund`.

An **Always allow** grant answers a step-up at once only when it covers every requested scope. A `403 insufficient_scope` without `AAuth-Requirement` is not a step-up: no enabled scope allows the request.

## Token lifetimes[​](#token-lifetimes)

TokenLifetime (defaults)Agent tokenSet by your agent provider. The protocol caps it at 24 hours.Person tokenAt most 1 hour, and never past the agent token's `exp`Auth tokenAt most 1 hour, and never past the agent token's `exp` or the presented token's `exp`Resource token5 minutes. Used once at the person server; a retry with the same key gets the same pending request back.Pending request and its code10 minutes

DreamFactory refuses a person or auth token whose `exp` is more than one hour after its `iat` ("Token lifetime exceeds 1 hour"), whichever person server issued it. The DreamFactory admin can change these defaults, but not lift person and auth tokens above one hour (see [Configuration reference](/Security/aauth/install#configuration-reference)).

There are no refresh tokens. Because an auth token never outlives the person token it was issued for, renewing an auth token with the same person token does not extend the session; it helps only when the admin set auth tokens shorter than person tokens. When the person token nears its expiry, ask for a new one (step 2): the person has to open the link and continue again, and with an **Always allow** grant the auth token request that follows is answered at once. Plan for one person interaction per hour of continuous work in df-aauth 0.1.0.

## Errors[​](#errors)

The challenges and the refusals a client most often meets:

Status`error`MeansDo`401``person_token_required`Signed with an agent token onlyGet a person token (step 2)`401``auth_token_required`Signed with a person token; the challenge carries a resource tokenGet an auth token (step 6)`401``insufficient_scope` with `AAuth-Requirement`Step-upGet an auth token for the new resource token`401`Any, with a `Signature-Error` headerThe signature or a token did not verifySee the codes below`403``insufficient_scope` without `AAuth-Requirement`No enabled scope allows the request, the person no longer holds the role, or the role is unavailableAsk the DreamFactory admin; don't retry`403``agent_blocked`An admin blocked this agent, or another agent id your request key has presented here. A new agent id in your agent token does not change that. A request with DreamFactory's own person or auth token belongs to the agent the token was issued for.Stop`403``too_many_agents`Your request key has already presented agent tokens for 20 agent ids at this DreamFactory. From the APIs, `/aauth/authorize` and the person server.Use one request key per agent id`403``denied`The person is no longer active, or (when polling) the person declinedStop, or ask again`403``user_unreachable``capabilities` lacks `"interaction"`Declare it`400``invalid_request`Malformed body, API key or session token mixed with AAuth, method override, multipart body, `mission_s256`Fix the request`400``invalid_resource_token`, `invalid_presented_token`, `expired_resource_token`, `expired_presented_token`The person server's checks failedCall the API again for a fresh resource token`400``invalid_scope``/aauth/authorize` got a scope that is not availableUse a scope from `scope_descriptions``408`, `410``expired`, `invalid_code`The pending request endedStart that step again`429``rate_limited`Too many pending requests (`Retry-After: 60`)Back off`503``temporarily_unavailable`DreamFactory could not check whether your agent is blocked (from the APIs, `/aauth/authorize` and the person server), or which agent one of its own tokens was issued for (from the APIs and `/aauth/authorize`). `Retry-After: 30`.Retry after `Retry-After``404``not_found`From `/aauth/*` or `/.well-known/aauth-*`: AAuth, or DreamFactory's own person server, is offStop. While AAuth is off, signed API calls get DreamFactory's normal "no API key" error.

`Signature-Error` codes: `invalid_signature` (a missing header, wrong host, bad signature, replay, stale `created` or a body that doesn't match `Content-Digest`), `invalid_input` with `required_input=(...)` (a required component is not covered), `clock_skew` (`created` or `iat` in the future), `unsupported_scheme` (with `Accept-Signature-Scheme: jwt`), `unsupported_algorithm` (with `Accept-Signature-Alg: Ed25519, ES256`), `invalid_key`, `unknown_key` (also when your agent provider's documents can't be fetched), `issuer_missing`, `issuer_mismatch`, `invalid_jwt` (also for a person or auth token from a person server this DreamFactory doesn't trust, and with "This DreamFactory has no record of issuing this token. Get a new one." for one of its own tokens it has no record of: drop that token and get a new one) and `expired_jwt`.

Every message, with its cause and fix, is in the [error reference](/Security/aauth/troubleshooting#error-reference).

## Client checklist[​](#client-checklist)

- Agent provider metadata and JWKS served over https, without redirects; `issuer` equals the origin; the signing key has `alg` and the `kid` your tokens name.

- Agent id `aauth:<name>@<agent provider host>`; agent token with `typ` `aa-agent+jwt`, `dwk` `aauth-agent.json` and `cnf.jwk` with `alg`.

- Label `sig`; `@authority` is the issuer host; `@query` covered when there is a query; `content-type` and `content-digest` covered with a body; a fresh `created` for every request; the raw path and query signed.

- `401` handling for `requirement=person-token`, `requirement=auth-token` (including step-up), and `Signature-Error`.

- `202` handling: show the link and code, honor `Retry-After`, poll `Location` with the same key, stop on `403`, `408` and `410`, back off on `429`.

- Resource token, person token and auth token checks before use.

- Tokens cached per resource and person server, reused until shortly before they expire, and dropped when a request with them gets a `401` without an `auth-token` challenge (for example `invalid_jwt` or `expired_jwt`).

- One request key per agent id.

- A plan for the hourly person interaction: a way to reach the person with a new link.