Appwrite OAuth2 API
The OAuth2 service allows you to authorize apps and issue standards-based OAuth2 and OpenID Connect tokens. 14 operations across 12 paths in the Appwrite 2.0.0 OpenAPI.
The OAuth2 service allows you to authorize apps and issue standards-based OAuth2 and OpenID Connect tokens. 14 operations across 12 paths in the Appwrite 2.0.0 OpenAPI.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/appwrite-oauth2-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.0.0
info:
title: Appwrite Oauth2 API
description: Appwrite backend as a service cuts up to 70% of the time and costs required for building a modern application. We abstract and simplify common development tasks behind a REST APIs, to help you develop your app in a fast and secure way. For full API documentation and tutorials go to [https://appwrite.io/docs](https://appwrite.io/docs)
version: 2.0.0
termsOfService: https://appwrite.io/policy/terms
contact:
name: Appwrite Team
url: https://appwrite.io/support
email: team@appwrite.io
license:
name: BSD-3-Clause
url: https://raw.githubusercontent.com/appwrite/appwrite/master/LICENSE
servers:
- url: https://cloud.appwrite.io/v1
description: Appwrite Cloud endpoint.
- url: https://{region}.cloud.appwrite.io/v1
description: Appwrite Cloud regional endpoint. Replace `{region}` with your project region.
variables:
region:
default: fra
description: Appwrite Cloud region.
tags:
- name: oauth2
description: The OAuth2 service allows you to authorize apps and issue standards-based OAuth2 and OpenID Connect tokens.
paths:
/oauth2/{project_id}/approve:
post:
summary: Approve OAuth2
operationId: oauth2Approve
tags:
- oauth2
description: Approve an OAuth2 grant after the user gives consent. Returns the `redirectUrl` the end user should be sent to. The consent screen may optionally pass enriched `authorization_details` to record the concrete resources the user selected. You can pass Accept header of `application/json` to receive a JSON response instead of a redirect.
responses:
'200':
description: OAuth2 Approve
content:
application/json:
schema:
$ref: '#/components/schemas/oauth2Approve'
deprecated: false
x-appwrite:
group: authorization
demo: oauth2/approve.md
rate-limit: 10
rate-time: 60
rate-key: ip:{ip},userId:{userId}
scope: oauth2.write
platforms:
- console
- client
- server
packaging: false
public: true
auth:
console:
ProjectPath: []
client:
ProjectPath: []
server:
ProjectPath: []
Session: []
security:
- ProjectPath: []
Session: []
JWT: []
parameters:
- name: project_id
description: Project ID in which OAuth2 client exists.
required: true
schema:
type: string
example: <PROJECT_ID>
in: path
requestBody:
content:
application/json:
schema:
type: object
properties:
grant_id:
description: Grant ID made during authorization, provided to consent screen in URL search params.
type: string
example: <GRANT_ID>
authorization_details:
description: Enriched `authorization_details` the user consented to, replacing what the client requested. Each entry must use a `type` the project accepts. Optional; omit to keep the originally requested details.
type: string
default: ''
example: <AUTHORIZATION_DETAILS>
scope:
description: Space-separated scopes the user consented to. Must be a subset of the scopes originally requested; identity scopes such as `openid` are always retained. Optional; omit to keep the originally requested scopes.
type: string
default: ''
example: <SCOPE>
required:
- grant_id
/oauth2/{project_id}/authorize:
get:
summary: OAuth2 Authorize
operationId: oauth2Authorize
tags:
- oauth2
description: Begin the OAuth2 authorization flow. When called without a session, the user is redirected to the consent screen without grant ID. When called with a session, the redirect URL includes param for grant ID. You can pass Accept header of `application/json` to receive a JSON response instead of a redirect.
responses:
'200':
description: OAuth2 Authorize
content:
application/json:
schema:
$ref: '#/components/schemas/oauth2Authorize'
deprecated: false
x-appwrite:
group: authorization
demo: oauth2/authorize.md
rate-limit: 60
rate-time: 60
rate-key: url:{url},ip:{ip}
scope: public
platforms:
- console
- client
- server
packaging: false
public: true
auth:
console:
ProjectPath: []
client:
ProjectPath: []
server:
ProjectPath: []
Session: []
security:
- ProjectPath: []
Session: []
JWT: []
parameters:
- name: project_id
description: Project ID in which OAuth2 client exists.
required: true
schema:
type: string
example: <PROJECT_ID>
in: path
- name: client_id
description: OAuth2 client ID. Either a registered app ID or an HTTPS client ID metadata document URL.
required: false
schema:
type: string
example: <CLIENT_ID>
default: ''
in: query
- name: redirect_uri
description: Redirect URI where visitor will be redirected after authorization, whether successful or not.
required: false
schema:
type: string
format: url
example: https://example.com
default: ''
in: query
- name: response_type
description: OAuth2 / OIDC response type. One of `code` (Authorization Code Flow), `id_token` (Implicit Flow, OIDC login only), or `code id_token` (Hybrid Flow).
required: false
schema:
type: string
example: ''
default: ''
in: query
- name: scope
description: 'Space-separated OAuth2 scopes. Can include project scopes, and built-in scopes: `openid`, `email`, `profile`, `phone`.'
required: false
schema:
type: string
example: <SCOPE>
default: ''
in: query
- name: state
description: OAuth2 state. You receive this back in the redirect URI.
required: false
schema:
type: string
example: <STATE>
default: ''
in: query
- name: nonce
description: OIDC nonce parameter to prevent replay attacks. Required when response_type includes `id_token`.
required: false
schema:
type: string
example: <NONCE>
default: ''
in: query
- name: code_challenge
description: PKCE code challenge. Required when OAuth2 app is public.
required: false
schema:
type: string
example: <CODE_CHALLENGE>
default: ''
in: query
- name: code_challenge_method
description: PKCE code challenge method. Required when OAuth2 app is public.
required: false
schema:
type: string
example: s256
default: ''
in: query
- name: prompt
description: 'OIDC prompt parameter for customization of consent screen. Space-separated list of: none, login, consent, select_account.'
required: false
schema:
type: string
example: <PROMPT>
default: ''
in: query
- name: max_age
description: OIDC max_age paraleter for customization of consent screen. Maximum allowable elapsed time in seconds since the user last authenticated. If exceeded, re-authentication is required.
required: false
schema:
type: integer
format: int32
example: 0
in: query
- name: authorization_details
description: Rich authorization request. JSON array of objects, each with a `type` and project-defined fields
required: false
schema:
type: string
example: <AUTHORIZATION_DETAILS>
default: ''
in: query
- name: resource
description: RFC 8707 resource indicator URI or URI list. Each value must be an absolute URI without a fragment.
required: false
schema:
type: string
default: []
in: query
- name: audience
description: Compatibility alias for a single OAuth2 resource indicator URI.
required: false
schema:
type: string
example: <AUDIENCE>
default: ''
in: query
- name: request_uri
description: OAuth2 authorization request handle returned by the pushed authorization request endpoint.
required: false
schema:
type: string
example: <REQUEST_URI>
default: ''
in: query
post:
summary: OAuth2 Authorize
operationId: oauth2AuthorizePost
tags:
- oauth2
description: Begin the OAuth2 authorization flow. When called without a session, the user is redirected to the consent screen without grant ID. When called with a session, the redirect URL includes param for grant ID. You can pass Accept header of `application/json` to receive a JSON response instead of a redirect.
responses:
'200':
description: OAuth2 Authorize
content:
application/json:
schema:
$ref: '#/components/schemas/oauth2Authorize'
deprecated: false
x-appwrite:
group: authorization
demo: oauth2/authorize.md
rate-limit: 60
rate-time: 60
rate-key: url:{url},ip:{ip}
scope: public
platforms:
- console
- client
- server
packaging: false
public: true
auth:
console:
ProjectPath: []
client:
ProjectPath: []
server:
ProjectPath: []
Session: []
security:
- ProjectPath: []
Session: []
JWT: []
parameters:
- name: project_id
description: Project ID in which OAuth2 client exists.
required: true
schema:
type: string
example: <PROJECT_ID>
in: path
requestBody:
content:
application/json:
schema:
type: object
properties:
client_id:
description: OAuth2 client ID. Either a registered app ID or an HTTPS client ID metadata document URL.
type: string
default: ''
example: <CLIENT_ID>
redirect_uri:
description: Redirect URI where visitor will be redirected after authorization, whether successful or not.
type: string
default: ''
example: https://example.com
format: url
response_type:
description: OAuth2 / OIDC response type. One of `code` (Authorization Code Flow), `id_token` (Implicit Flow, OIDC login only), or `code id_token` (Hybrid Flow).
type: string
default: ''
example: ''
scope:
description: 'Space-separated OAuth2 scopes. Can include project scopes, and built-in scopes: `openid`, `email`, `profile`, `phone`.'
type: string
default: ''
example: <SCOPE>
state:
description: OAuth2 state. You receive this back in the redirect URI.
type: string
default: ''
example: <STATE>
nonce:
description: OIDC nonce parameter to prevent replay attacks. Required when response_type includes `id_token`.
type: string
default: ''
example: <NONCE>
code_challenge:
description: PKCE code challenge. Required when OAuth2 app is public.
type: string
default: ''
example: <CODE_CHALLENGE>
code_challenge_method:
description: PKCE code challenge method. Required when OAuth2 app is public.
type: string
default: ''
example: s256
prompt:
description: 'OIDC prompt parameter for customization of consent screen. Space-separated list of: none, login, consent, select_account.'
type: string
default: ''
example: <PROMPT>
max_age:
description: OIDC max_age paraleter for customization of consent screen. Maximum allowable elapsed time in seconds since the user last authenticated. If exceeded, re-authentication is required.
type: integer
example: 0
format: int32
nullable: true
authorization_details:
description: Rich authorization request. JSON array of objects, each with a `type` and project-defined fields
type: string
default: ''
example: <AUTHORIZATION_DETAILS>
resource:
description: RFC 8707 resource indicator URI or URI list. Each value must be an absolute URI without a fragment.
type: string
default: []
audience:
description: Compatibility alias for a single OAuth2 resource indicator URI.
type: string
default: ''
example: <AUDIENCE>
request_uri:
description: OAuth2 authorization request handle returned by the pushed authorization request endpoint.
type: string
default: ''
example: <REQUEST_URI>
/oauth2/{project_id}/device_authorization:
post:
summary: OAuth2 Device Authorization
operationId: oauth2CreateDeviceAuthorization
tags:
- oauth2
description: Start the OAuth2 Device Authorization Grant. Returns the device code, user code, verification URL, expiration, and polling interval.
responses:
'200':
description: OAuth2 Device Authorization
content:
application/json:
schema:
$ref: '#/components/schemas/oauth2DeviceAuthorization'
deprecated: false
x-appwrite:
group: authorization
demo: oauth2/create-device-authorization.md
rate-limit: 60
rate-time: 60
rate-key: url:{url},ip:{ip}
scope: public
platforms:
- console
- client
- server
packaging: false
public: true
auth:
console:
ProjectPath: []
client:
ProjectPath: []
server:
ProjectPath: []
Session: []
security:
- ProjectPath: []
Session: []
JWT: []
Key: []
parameters:
- name: project_id
description: Project ID in which OAuth2 client exists.
required: true
schema:
type: string
example: <PROJECT_ID>
in: path
requestBody:
content:
application/json:
schema:
type: object
properties:
client_id:
description: OAuth2 client ID. Either a registered app ID or an HTTPS client ID metadata document URL.
type: string
default: ''
example: <CLIENT_ID>
scope:
description: 'Space-separated OAuth2 scopes. Can include project scopes, and built-in scopes: `openid`, `email`, `profile`.'
type: string
default: ''
example: <SCOPE>
authorization_details:
description: Rich authorization request. JSON array of objects, each with a `type` and project-defined fields
type: string
default: ''
example: <AUTHORIZATION_DETAILS>
resource:
description: RFC 8707 resource indicator URI or URI list. Each value must be an absolute URI without a fragment.
type: string
default: []
audience:
description: Compatibility alias for a single OAuth2 resource indicator URI.
type: string
default: ''
example: <AUDIENCE>
/oauth2/{project_id}/grants:
post:
summary: Create OAuth2 Grant
operationId: oauth2CreateGrant
tags:
- oauth2
description: Exchange a device flow user code for an OAuth2 grant. The authenticated user is bound to the pending grant. Pass the returned grant ID to the get grant endpoint to render the consent screen, then to the approve or reject endpoint to complete the flow.
responses:
'201':
description: OAuth2 Grant
content:
application/json:
schema:
$ref: '#/components/schemas/oauth2Grant'
deprecated: false
x-appwrite:
group: grants
demo: oauth2/create-grant.md
rate-limit: 10
rate-time: 60
rate-key: ip:{ip},userId:{userId}
scope: oauth2.write
platforms:
- console
- client
- server
packaging: false
public: true
auth:
console:
ProjectPath: []
client:
ProjectPath: []
server:
ProjectPath: []
Session: []
security:
- ProjectPath: []
Session: []
JWT: []
parameters:
- name: project_id
description: Project ID in which OAuth2 client exists.
required: true
schema:
type: string
example: <PROJECT_ID>
in: path
requestBody:
content:
application/json:
schema:
type: object
properties:
user_code:
description: User code displayed on the device.
type: string
example: <USER_CODE>
required:
- user_code
/oauth2/{project_id}/grants/{grant_id}:
get:
summary: Get OAuth2 Grant
operationId: oauth2GetGrant
tags:
- oauth2
description: Get an OAuth2 grant by its ID. Used by the consent screen to display the details of the authorization the user is being asked to approve. A grant can only be read by the user it belongs to, or by server SDK.
responses:
'200':
description: OAuth2 Grant
content:
application/json:
schema:
$ref: '#/components/schemas/oauth2Grant'
deprecated: false
x-appwrite:
group: grants
demo: oauth2/get-grant.md
rate-limit: 60
rate-time: 60
rate-key: ip:{ip},userId:{userId}
scope: oauth2.read
platforms:
- console
- client
- server
packaging: false
public: true
auth:
console:
ProjectPath: []
client:
ProjectPath: []
server:
ProjectPath: []
Session: []
security:
- ProjectPath: []
Session: []
JWT: []
Key: []
parameters:
- name: project_id
description: Project ID in which OAuth2 client that created grant during authorization exists.
required: true
schema:
type: string
example: <PROJECT_ID>
in: path
- name: grant_id
description: Grant ID made during authorization, provided to consent screen in URL search params.
required: true
schema:
type: string
example: <GRANT_ID>
in: path
/oauth2/{project_id}/logout:
get:
summary: OAuth2 Logout
operationId: oauth2Logout
tags:
- oauth2
description: OpenID Connect RP-Initiated Logout. Ends the user session and revokes the tokens issued to the app identified by the `id_token_hint`, then redirects the user to `post_logout_redirect_uri` when it matches a URI registered on the app.
responses:
'204':
description: No content
deprecated: false
x-appwrite:
group: tokens
demo: oauth2/logout.md
rate-limit: 10
rate-time: 60
rate-key: url:{url},ip:{ip}
scope: public
platforms:
- console
- client
packaging: false
public: true
auth:
console:
ProjectPath: []
client:
ProjectPath: []
security:
- ProjectPath: []
Session: []
parameters:
- name: project_id
description: Project ID in which OAuth2 client exists.
required: true
schema:
type: string
example: <PROJECT_ID>
in: path
- name: id_token_hint
description: ID Token previously issued to the app, used as proof of the logout request. Required to end the session; signature and issuer are validated while expiry is ignored.
required: false
schema:
type: string
example: <ID_TOKEN_HINT>
default: ''
in: query
- name: logout_hint
description: Hint about the user that is logging out. Accepted for OIDC compatibility.
required: false
schema:
type: string
example: <LOGOUT_HINT>
default: ''
in: query
- name: client_id
description: OAuth2 client ID. When both `client_id` and `id_token_hint` are provided, they must identify the same app.
required: false
schema:
type: string
example: <CLIENT_ID>
default: ''
in: query
- name: post_logout_redirect_uri
description: URI to redirect the user to after logout. Must exactly match a URI registered in the app's `postLogoutRedirectUris`.
required: false
schema:
type: string
format: url
example: https://example.com
default: ''
in: query
- name: state
description: Opaque value passed back unchanged in the `state` query param of the post-logout redirect.
required: false
schema:
type: string
example: <STATE>
default: ''
in: query
- name: ui_locales
description: Preferred languages for any logout UI, as space-separated BCP47 tags. Accepted for OIDC compatibility.
required: false
schema:
type: string
example: <UI_LOCALES>
default: ''
in: query
post:
summary: OAuth2 Logout
operationId: oauth2LogoutPost
tags:
- oauth2
description: OpenID Connect RP-Initiated Logout. Ends the user session and revokes the tokens issued to the app identified by the `id_token_hint`, then redirects the user to `post_logout_redirect_uri` when it matches a URI registered on the app.
responses:
'204':
description: No content
deprecated: false
x-appwrite:
group: tokens
demo: oauth2/logout.md
rate-limit: 10
rate-time: 60
rate-key: url:{url},ip:{ip}
scope: public
platforms:
- console
- client
packaging: false
public: true
auth:
console:
ProjectPath: []
client:
ProjectPath: []
security:
- ProjectPath: []
Session: []
parameters:
- name: project_id
description: Project ID in which OAuth2 client exists.
required: true
schema:
type: string
example: <PROJECT_ID>
in: path
requestBody:
content:
application/json:
schema:
type: object
properties:
id_token_hint:
description: ID Token previously issued to the app, used as proof of the logout request. Required to end the session; signature and issuer are validated while expiry is ignored.
type: string
default: ''
example: <ID_TOKEN_HINT>
logout_hint:
description: Hint about the user that is logging out. Accepted for OIDC compatibility.
type: string
default: ''
example: <LOGOUT_HINT>
client_id:
description: OAuth2 client ID. When both `client_id` and `id_token_hint` are provided, they must identify the same app.
type: string
default: ''
example: <CLIENT_ID>
post_logout_redirect_uri:
description: URI to redirect the user to after logout. Must exactly match a URI registered in the app's `postLogoutRedirectUris`.
type: string
default: ''
example: https://example.com
format: url
state:
description: Opaque value passed back unchanged in the `state` query param of the post-logout redirect.
type: string
default: ''
example: <STATE>
ui_locales:
description: Preferred languages for any logout UI, as space-separated BCP47 tags. Accepted for OIDC compatibility.
type: string
default: ''
example: <UI_LOCALES>
/oauth2/{project_id}/organizations:
get:
summary: OAuth2 List Accessible Organizations
operationId: oauth2ListOrganizations
tags:
- oauth2
description: List the organizations the OAuth2 access token can access. Resolves the token's `organization` authorization details, expanding the `*` wildcard into the concrete set of organizations the user can see.
responses:
'200':
description: OAuth2 accessible organizations list
content:
application/json:
schema:
$ref: '#/components/schemas/oauth2OrganizationList'
deprecated: false
x-appwrite:
group: platform
demo: oauth2/list-organizations.md
rate-limit: 120
rate-time: 60
rate-key: url:{url},ip:{ip}
scope: oauth2.organizations.read
platforms:
- console
- client
- server
packaging: false
public: true
auth:
console:
ProjectPath: []
client:
ProjectPath: []
server:
ProjectPath: []
Session: []
security:
- ProjectPath: []
Session: []
JWT: []
Key: []
parameters:
- name: project_id
description: Project ID of the console project the OAuth2 access token was issued for.
required: true
schema:
type: string
example: <PROJECT_ID>
in: path
- name: limit
description: Maximum number of organizations to return. Between 1 and 5000.
required: false
schema:
type: integer
format: int32
example: 1
default: 25
in: query
- name: offset
description: Number of organizations to skip before returning results. Used for pagination.
required: false
schema:
type: integer
format: int32
example: 0
default: 0
in: query
- name: search
description: 'Search term to filter your list results. Max length: 256 chars.'
required: false
schema:
type: string
example: <SEARCH>
default: ''
in: query
/oauth2/{project_id}/par:
post:
summary: OAuth2 PAR
operationId: oauth2CreatePAR
tags:
- oauth2
description: Store an OAuth2 authorization request server-side and receive a short-lived request_uri handle for the authorize endpoint.
responses:
'201':
description: OAuth2 PAR
content:
application/json:
schema:
$ref: '#/components/schemas/oauth2PAR'
deprecated: false
x-appwrite:
group: authorization
demo: oauth2/create-par.md
rate-limit: 60
rate-time: 60
rate-key: url:{url},ip:{ip}
scope: public
platforms:
- console
- client
- server
packaging: false
public: true
auth:
console:
ProjectPath: []
client:
ProjectPath: []
server:
ProjectPath: []
Session: []
security:
- ProjectPath: []
Session: []
JWT: []
Key: []
parameters:
- name: project_id
description: Project ID in which OAuth2 client exists.
required: true
schema:
type: string
example: <PROJECT_ID>
in: path
requestBody:
content:
application/json:
schema:
type: object
properties:
client_id:
description: OAuth2 client ID. Either a registered app ID or an HTTPS client ID metadata document URL.
type: string
example: <CLIENT_ID>
redirect_uri:
description: Redirect URI where visitor will be redirected after authorization, whether successful or not.
type: string
example: https://example.com
format: url
response_type:
description: OAuth2 / OIDC response type.
type: string
example: code
scope:
description: 'Space-separated OAuth2 scopes. Can include project scopes, and built-in scopes: `openid`, `email`, `profile`, `phone`.'
type: string
default: ''
example: <SCOPE>
state:
description: OAuth2 state. You receive this back in the redirect URI.
type: string
default: ''
example: <STATE>
nonce:
description: OIDC nonce parameter to prevent replay attacks. Required when response_type includes `id_token`.
type: string
default: ''
example: <NONCE>
code_challenge:
description: PKCE code challenge. Required when OAuth2 app is public.
type: string
default: ''
example: <CODE_CHALLENGE>
code_challenge_method:
description: PKCE code challenge method. Required when OAuth2 app is public.
type: string
default: ''
example: s256
prompt:
description: 'OIDC prompt parameter for customization of consent screen. Space-separated list of: none, login, consent, select_account.'
type: string
default: ''
example: <PROMPT>
max_age:
description: OIDC max_age parameter for customization of consent screen.
type: integer
example: 0
format: int32
nullable: true
authorization_details:
description: Rich authorization request. JSON array of objects, each with a `type` and project-defined fields
type: string
default: ''
example: <AUTHORIZATION_DETAILS>
resource:
description: RFC 8707 resource indicator URI or URI list. Each value must be an absolute URI without a fragment.
type: string
de
# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/appwrite/refs/heads/main/openapi/appwrite-oauth2-api-openapi.yml