OAuth consent API reference

Updated Nov 13, 2026

5 operations of the Fax for Agents API, from the OpenAPI document version 1.20.0, snapshot of 2026-11-13. The base URL is https://api.faxforagents.com/v1. This is one group of the full reference.

Allowing an authorization mints the authorization code and returns where the browser goes next.
Denying an authorization sends the app an access_denied answer.
An OAuth access token works on the MCP server only, and the REST API answers it with 401.

Operations

GET /v1/oauth/authorizations/{authorization_id} The pending consent behind a consent URL: the app, the scopes and your organizations
POST /v1/oauth/authorizations/{authorization_id}/approve Allow: mint the authorization code and return where the browser goes next
POST /v1/oauth/authorizations/{authorization_id}/deny Deny: send the app an access_denied answer
GET /v1/oauth/grants Your connected apps in this organization
DELETE /v1/oauth/grants/{grant_id} Revoke a connected app

What is this group for?

For the consent screen. When an AI client connects to the MCP server with OAuth, it sends the person to a consent URL. The dashboard reads the pending authorization from this group, shows it, and posts the person's answer. The token endpoints of the OAuth flow are outside /v1 and are not part of this document.

GET /v1/oauth/authorizations/{authorization_id} returns the pending consent. client is the app that asks, and redirect_host is the host it will return to. The answer also has the scopes_requested, the person's organizations and the default environment. It expires at expires_at. The call takes a signed-in session.

How is the answer given?

POST /v1/oauth/authorizations/{authorization_id}/approve allows. The body names the org_id and the environment the app is connected to. It mints the authorization code and returns redirect_to, the address the browser opens next. auto_send is the consent screen's checkbox, for owners only.

POST /v1/oauth/authorizations/{authorization_id}/deny denies. The app gets an access_denied answer through the same redirect_to.

How are connected apps listed and revoked?

GET /v1/oauth/grants lists the connected apps of the organization. DELETE /v1/oauth/grants/{grant_id} revokes one, and that connection's tokens stop working. Both need key:admin, the scope that also guards API keys.

Revoking an app does not cancel a fax that is already queued. The OAuth guide walks through the screen a person sees.

Does an OAuth token work on this API?

No. An access token from the MCP sign-in works on the MCP server only. The REST API answers it with 401 invalid_token. A script that calls REST uses an API key from the identity group.

Each operation in detail

GET `/v1/oauth/authorizations/{authorization_id}`

The pending consent behind a consent URL: the app, the scopes and your organizations

Credential: a signed-in session.

Parameters

GET /v1/oauth/authorizations/{authorization_id} parameters
Name	In	Type	Required	Notes
`authorization_id`	path	string	yes

Responses

GET /v1/oauth/authorizations/{authorization_id} responses
Status	Meaning
`200`	Successful Response
`401`	No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused.
`404`	not_found: no such resource for this credential. A resource of another organization answers the same.
`422`	A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule.
`429`	rate_limited. Retry-After and the RateLimit-* headers say when to try again.

Response fields

GET /v1/oauth/authorizations/{authorization_id} response fields
Field	Type	Required
`client`	object OAuthConsentClient	yes
`default_environment`	string (live, test)	yes
`expires_at`	string	yes
`id`	string	yes
`organizations`	array of object OAuthConsentOrganization	yes
`redirect_host`	string	yes
`scopes_requested`	array of string	yes

Example

curl https://api.faxforagents.com/v1/oauth/authorizations/AUTHORIZATION_ID

POST `/v1/oauth/authorizations/{authorization_id}/approve`

Allow: mint the authorization code and return where the browser goes next

Credential: a signed-in session.

Parameters

POST /v1/oauth/authorizations/{authorization_id}/approve parameters
Name	In	Type	Required	Notes
`authorization_id`	path	string	yes
`Idempotency-Key`	header	string	no	Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.

Request body application/json, required

POST /v1/oauth/authorizations/{authorization_id}/approve request body
Field	Type	Required	Description
`auto_send`	boolean or null	no	The consent screen's checkbox, owners only: false turns the organization's auto-send setting off for this environment, true turns it on with its current limits. Omitted leaves it.
`environment`	string (live, test)	no
`org_id`	string	yes

Responses

POST /v1/oauth/authorizations/{authorization_id}/approve responses
Status	Meaning
`200`	Successful Response
`401`	No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused.
`403`	The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required.
`404`	not_found: no such resource for this credential. A resource of another organization answers the same.
`409`	The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state.
`422`	A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule.
`429`	rate_limited. Retry-After and the RateLimit-* headers say when to try again.

Response fields

POST /v1/oauth/authorizations/{authorization_id}/approve response fields
Field	Type	Required	Description
`redirect_to`	string	yes	Where the browser goes next: the client's registered redirect URI.

Example

curl https://api.faxforagents.com/v1/oauth/authorizations/AUTHORIZATION_ID/approve \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"org_id":"org_example"}'

POST `/v1/oauth/authorizations/{authorization_id}/deny`

Deny: send the app an access_denied answer

Credential: a signed-in session.

Parameters

POST /v1/oauth/authorizations/{authorization_id}/deny parameters
Name	In	Type	Required	Notes
`authorization_id`	path	string	yes
`Idempotency-Key`	header	string	no	Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.

Responses

POST /v1/oauth/authorizations/{authorization_id}/deny responses
Status	Meaning
`200`	Successful Response
`401`	No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused.
`403`	The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required.
`404`	not_found: no such resource for this credential. A resource of another organization answers the same.
`409`	The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state.
`422`	A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule.
`429`	rate_limited. Retry-After and the RateLimit-* headers say when to try again.

Response fields

POST /v1/oauth/authorizations/{authorization_id}/deny response fields
Field	Type	Required	Description
`redirect_to`	string	yes	Where the browser goes next: the client's registered redirect URI.

Example

curl https://api.faxforagents.com/v1/oauth/authorizations/AUTHORIZATION_ID/deny \
  -X POST

GET `/v1/oauth/grants`

Your connected apps in this organization

Credential: an API key or a signed-in session. Scope: key:admin.

Parameters

GET /v1/oauth/grants parameters
Name	In	Type	Required	Notes
`cursor`	query	string or null	no
`limit`	query	integer	no	Default `100`.

Responses

GET /v1/oauth/grants responses
Status	Meaning
`200`	Successful Response
`401`	No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused.
`403`	The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required.
`404`	not_found: no such resource for this credential. A resource of another organization answers the same.
`422`	A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule.
`429`	rate_limited. Retry-After and the RateLimit-* headers say when to try again.

Response fields

GET /v1/oauth/grants response fields
Field	Type	Required	Description
`items`	array of object Grant	yes
`next_cursor`	string or null	no

Example

curl https://api.faxforagents.com/v1/oauth/grants \
  -H "Authorization: Bearer ffa_test_..."

DELETE `/v1/oauth/grants/{grant_id}`

Revoke a connected app

Credential: an API key or a signed-in session. Scope: key:admin.

Parameters

DELETE /v1/oauth/grants/{grant_id} parameters
Name	In	Type	Required	Notes
`grant_id`	path	string	yes
`Idempotency-Key`	header	string	no	Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.

Responses

DELETE /v1/oauth/grants/{grant_id} responses
Status	Meaning
`204`	Successful Response
`401`	No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused.
`403`	The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required.
`404`	not_found: no such resource for this credential. A resource of another organization answers the same.
`409`	The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state.
`422`	A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule.
`429`	rate_limited. Retry-After and the RateLimit-* headers say when to try again.

Example

curl https://api.faxforagents.com/v1/oauth/grants/GRANT_ID \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

OAuth consent API reference

Operations

What is this group for?

What does the consent screen read?

How is the answer given?

How are connected apps listed and revoked?

Does an OAuth token work on this API?

Each operation in detail

GET /v1/oauth/authorizations/{authorization_id}

Parameters

Responses

Response fields

Example

POST /v1/oauth/authorizations/{authorization_id}/approve

Parameters

Request body application/json, required

Responses

Response fields

Example

POST /v1/oauth/authorizations/{authorization_id}/deny

Parameters

Responses

Response fields

Example

GET /v1/oauth/grants

Parameters

Responses

Response fields

Example

DELETE /v1/oauth/grants/{grant_id}

Parameters

Responses

Example

Measure this visit?

GET `/v1/oauth/authorizations/{authorization_id}`

POST `/v1/oauth/authorizations/{authorization_id}/approve`

POST `/v1/oauth/authorizations/{authorization_id}/deny`

GET `/v1/oauth/grants`

DELETE `/v1/oauth/grants/{grant_id}`