diff --git a/openapi-admin.yaml b/openapi-admin.yaml index 70df01b..81971cd 100644 --- a/openapi-admin.yaml +++ b/openapi-admin.yaml @@ -1,6 +1,6 @@ openapi: 3.0.3 info: - version: "1.2.0" + version: "3.0.4" title: "Hanko Admin API" description: | ## Introduction diff --git a/openapi-flow.yaml b/openapi-flow.yaml index 44ca6a6..bd46938 100644 --- a/openapi-flow.yaml +++ b/openapi-flow.yaml @@ -2,7 +2,7 @@ openapi: 3.0.3 info: title: Flow API description: Flow API - version: 1.2.0 + version: 3.0.4 servers: - url: "https://{tenant_id}.hanko.io" variables: diff --git a/openapi-public.yaml b/openapi-public.yaml index f0b29ce..f41b7dc 100644 --- a/openapi-public.yaml +++ b/openapi-public.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - version: '1.2.0' + version: '3.0.4' title: 'Hanko Public API' description: | ## Introduction @@ -78,482 +78,6 @@ paths: text/html: schema: type: string - /passcode/login/initialize: - post: - summary: 'Initialize passcode login' - description: | - Initialize a passcode login for the user identified by `user_id`. Sends an email - containing the actual passcode to the user's primary email address or to the address specified - through `email_id`. Returns a representation of the passcode. - operationId: passcodeInit - tags: - - Passcode - deprecated: true - requestBody: - content: - application/json: - schema: - type: object - properties: - user_id: - description: The ID of the user - allOf: - - $ref: '#/components/schemas/UUID4' - email_id: - description: The ID of the email address - allOf: - - $ref: '#/components/schemas/UUID4' - required: [user_id] - responses: - '200': - description: 'Successful passcode login initialization' - content: - application/json: - schema: - $ref: '#/components/schemas/Passcode' - '400': - $ref: '#/components/responses/BadRequest' - '500': - $ref: '#/components/responses/InternalServerError' - /passcode/login/finalize: - post: - summary: 'Finalize passcode login' - description: | - Finalize a passcode login given the `id` of the passcode and the actual `code` provided in the the email sent - to the user during initialization. - - On success, sets the User's `verified` status to `true`. - operationId: passcodeFinal - tags: - - Passcode - deprecated: true - requestBody: - content: - application/json: - schema: - type: object - properties: - id: - description: The ID of the passcode - allOf: - - $ref: '#/components/schemas/UUID4' - code: - type: string - minLength: 6 - maxLength: 6 - description: | - The actual passcode from the email sent to the user during initialization, - a string of 6 decimal digits - example: "897481" - responses: - '200': - description: 'Successful passcode login finalization' - headers: - X-Auth-Token: - description: | - Present only when enabled via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.enable_auth_token_header` - for purposes of cross-domain communication between client and Hanko API. - schema: - $ref: '#/components/schemas/X-Auth-Token' - X-Session-Lifetime: - description: | - Contains the seconds until the session expires. - schema: - $ref: '#/components/schemas/X-Session-Lifetime' - Set-Cookie: - description: | - Contains the JSON Web Token (JWT) that must be provided to protected endpoints. - Cookie attributes (e.g. domain) can be set via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.cookie`. - schema: - $ref: '#/components/schemas/CookieSession' - content: - application/json: - schema: - $ref: '#/components/schemas/Passcode' - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/Unauthorized' - '403': - $ref: '#/components/responses/Forbidden' - '408': - $ref: '#/components/responses/RequestTimeOut' - '410': - $ref: '#/components/responses/Gone' - '500': - $ref: '#/components/responses/InternalServerError' - /password/login: - post: - summary: 'Do password login' - description: | - Perform a password login for the user identified by `user_id` and a given `password`. - - This endpoint is only available if passwords have been enabled via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `passwords.enabled`. - operationId: passwordLogin - tags: - - Password - deprecated: true - requestBody: - content: - application/json: - schema: - type: object - properties: - user_id: - description: The ID of the user to perform a password login for - allOf: - - $ref: '#/components/schemas/UUID4' - password: - $ref: '#/components/schemas/Password' - required: - - user_id - - password - responses: - '200': - description: 'Successful password login' - headers: - X-Auth-Token: - description: | - Present only when enabled via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.enable_auth_token_header` - for purposes of cross-domain communication between client and Hanko API. - schema: - $ref: '#/components/schemas/X-Auth-Token' - X-Session-Lifetime: - description: | - Contains the seconds until the session expires. - schema: - $ref: '#/components/schemas/X-Session-Lifetime' - Set-Cookie: - description: | - Contains the JSON Web Token (JWT) that must be provided to protected endpoints. - Cookie attributes (e.g. domain) can be set via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.cookie`. - schema: - $ref: '#/components/schemas/CookieSession' - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/Unauthorized' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServerError' - /password: - put: - summary: 'Create/Set a password' - description: | - Create a or update an existing `password` for the user identified by `user_id`. - - This endpoint is only available if passwords have been enabled via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `passwords.enabled`. - operationId: password - tags: - - Password - deprecated: true - security: - - CookieAuth: [ ] - - BearerTokenAuth: [ ] - requestBody: - content: - application/json: - schema: - type: object - properties: - user_id: - description: The ID of the user to create/set a password for - allOf: - - $ref: '#/components/schemas/UUID4' - password: - $ref: '#/components/schemas/Password' - required: - - user_id - - password - responses: - '200': - description: 'Successful password update' - '201': - description: 'Successful password creation' - '400': - $ref: '#/components/responses/BadRequest' - '403': - $ref: '#/components/responses/Forbidden' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServerError' - /webauthn/login/initialize: - post: - summary: 'Initialize WebAuthn login' - description: | - Initialize a login with Webauthn. Returns a JSON representation of CredentialRequestOptions for use - with the Webauthn API's `navigator.credentials.get()`. - - Omitting the optional request body or using an empty JSON object results in generation of request options for a - login using a [discoverable credential](https://www.w3.org/TR/webauthn-2/#client-side-discoverable-public-key-credential-source) - (i.e. they will not contain - [allowCredentials](https://www.w3.org/TR/webauthn-2/#dom-publickeycredentialrequestoptions-allowcredentials)). - - *Note*: The Webauthn API uses binary data represented by ArrayBuffers for certain input/output values. - The Hanko API returns these values as base64url-encoded, so they must be converted to ArrayBuffers - when passed to the Webauthn API. Similarly, Webauthn API output must be converted to base64url-encoded values - when passed to the Hanko API (e.g. using the [webauthn-json](https://github.com/github/webauthn-json) library). - operationId: webauthnLoginInit - tags: - - WebAuthn - deprecated: true - requestBody: - content: - application/json: - schema: - type: object - properties: - user_id: - description: The ID of the user on whose behalf WebAuthn login should be performed - allOf: - - $ref: '#/components/schemas/UUID4' - responses: - '200': - description: 'Successful initialization' - content: - application/json: - schema: - $ref: '#/components/schemas/CredentialRequestOptions' - examples: - non-disco: - summary: Non-Discoverable credentials - value: - publicKey: - challenge: qgOI+0KpGnl9NOqaT6dfsYvi96R87LgpErnvePeOgSU= - timeout: 60000 - rpId: localhost - allowCredentials: - - type: public-key - id: Mepptysj5ZZrTlg0qiLbsZ068OtQMeGVAikVy2n1hvvG... - userVerification: required - disco: - summary: Discoverable credentials - value: - challenge: qgOI+0KpGnl9NOqaT6dfsYvi96R87LgpErnvePeOgSU= - timeout: 60000 - rpId: localhost - userVerification: required - '400': - $ref: '#/components/responses/BadRequest' - '500': - $ref: '#/components/responses/InternalServerError' - /webauthn/login/finalize: - post: - summary: 'Finalize WebAuthn login' - description: | - Finalize a login with Webauthn using the WebAuthn API response to a `navigator.credentials.get()` call. - - *Note*: The Webauthn API uses binary data represented by ArrayBuffers for certain input/output values. - The Hanko API returns these values as base64url-encoded, so they must be converted to ArrayBuffers - when passed to the Webauthn API. Similarly, Webauthn API output must be converted to base64url-encoded values - when passed to the Hanko API (e.g. using the [webauthn-json](https://github.com/github/webauthn-json) library). - operationId: webauthnLoginFinal - tags: - - WebAuthn - deprecated: true - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PublicKeyCredentialAssertionResponse' - responses: - '200': - description: 'Successful login' - headers: - X-Auth-Token: - description: | - Present only when enabled via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.enable_auth_token_header` - for purposes of cross-domain communication between client and Hanko API. - schema: - $ref: '#/components/schemas/X-Auth-Token' - X-Session-Lifetime: - description: | - Contains the seconds until the session expires. - schema: - $ref: '#/components/schemas/X-Session-Lifetime' - Set-Cookie: - description: | - Contains the JSON Web Token (JWT) that must be provided to protected endpoints. - Cookie attributes (e.g. domain) can be set via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.cookie`. - schema: - $ref: '#/components/schemas/CookieSession' - content: - application/json: - schema: - $ref: '#/components/schemas/WebauthnLoginResponse' - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/Unauthorized' - '500': - $ref: '#/components/responses/InternalServerError' - /webauthn/registration/initialize: - post: - summary: 'Initialize WebAuthn registration' - description: | - Initialize a registration with Webauthn. Returns a JSON representation of CredentialCreationOptions for use - with the Webauthn API's `navigator.credentials.create()`. - - *Note*: The Webauthn API uses binary data represented by ArrayBuffers for certain input/output values. - The Hanko API returns these values as base64url-encoded, so they must be converted to ArrayBuffers - when passed to the Webauthn API. Similarly, Webauthn API output must be converted to base64url-encoded values - when passed to the Hanko API (e.g. using the [webauthn-json](https://github.com/github/webauthn-json) library). - operationId: webauthnRegInit - tags: - - WebAuthn - deprecated: true - security: - - CookieAuth: [ ] - - BearerTokenAuth: [ ] - responses: - '200': - description: 'Challenge' - content: - application/json: - schema: - $ref: '#/components/schemas/CredentialCreationOptions' - '400': - $ref: '#/components/responses/BadRequest' - '422': - $ref: '#/components/responses/unprocessableEntity' - '500': - $ref: '#/components/responses/InternalServerError' - /webauthn/registration/finalize: - post: - summary: 'Finalize WebAuthn registration' - description: | - Finalize a registration with Webauthn using the WebAuthn API response to a `navigator.credentials.create()` call. - - *Note*: The Webauthn API uses binary data represented by ArrayBuffers for certain input/output values. - The Hanko API returns these values as base64url-encoded, so they must be converted to ArrayBuffers - when passed to the Webauthn API. Similarly, Webauthn API output must be converted to base64url-encoded values - when passed to the Hanko API (e.g. using the [webauthn-json](https://github.com/github/webauthn-json) library). - operationId: webauthnRegFinal - tags: - - WebAuthn - deprecated: true - security: - - CookieAuth: [ ] - - BearerTokenAuth: [ ] - requestBody: - description: "Challenge response" - content: - application/json: - schema: - $ref: '#/components/schemas/PublicKeyCredentialAttestationResponse' - responses: - '200': - description: 'Successful registration' - content: - application/json: - schema: - type: object - properties: - credential_id: - description: The ID of the created credential - type: string - format: base64 - user_id: - description: The ID of the user on whose behalf a credential was created - allOf: - - $ref: '#/components/schemas/UUID4' - '400': - $ref: '#/components/responses/BadRequest' - '500': - $ref: '#/components/responses/InternalServerError' - /webauthn/credentials: - get: - summary: 'Get a list of WebAuthn credentials' - description: | - Returns a list of WebAuthn credentials assigned to the current user. - operationId: listCredentials - tags: - - WebAuthn - deprecated: true - security: - - CookieAuth: [ ] - - BearerTokenAuth: [ ] - responses: - '200': - description: 'A list of WebAuthn credentials assigned to the current user' - content: - application/json: - schema: - $ref: '#/components/schemas/WebauthnCredentials' - '401': - $ref: '#/components/responses/Unauthorized' - '500': - $ref: '#/components/responses/InternalServerError' - /webauthn/credentials/{id}: - patch: - summary: 'Updates a WebAuthn credential' - description: | - Updates the specified WebAuthn credential. Only credentials assigned to the current user can be updated. - operationId: updateCredential - tags: - - WebAuthn - deprecated: true - security: - - CookieAuth: [ ] - - BearerTokenAuth: [ ] - parameters: - - name: id - in: path - description: ID of the WebAuthn credential - required: true - schema: - $ref: '#/components/schemas/UUID4' - requestBody: - content: - application/json: - schema: - type: object - properties: - name: - description: "A new credential name. Has no technical meaning, only serves as an identification aid for the user." - type: string - responses: - '200': - description: 'Credential updated successfully' - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/Unauthorized' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServerError' - delete: - summary: 'Deletes a WebAuthn credential' - description: | - Deletes the specified WebAuthn credential. - operationId: deleteCredential - tags: - - WebAuthn - deprecated: true - security: - - CookieAuth: [ ] - - BearerTokenAuth: [ ] - parameters: - - name: id - in: path - description: ID of the WebAuthn credential - required: true - schema: - $ref: '#/components/schemas/UUID4' - responses: - '201': - description: 'Credential updated successfully' - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/Unauthorized' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServerError' /.well-known/jwks.json: get: summary: 'Get JSON Web Key Set' @@ -566,122 +90,12 @@ paths: responses: '200': description: 'JSON Web Key Set' - content: - application/json: - schema: - $ref: '#/components/schemas/JSONWebKeySet' - '500': - $ref: '#/components/responses/InternalServerError' - /.well-known/config: - get: - deprecated: true - summary: 'Get public Hanko configuration' - description: | - Retrieve public backend configuration options. - - Useful for example for conditionally constructing a UI based on the options (e.g. don't show password - inputs when they are disabled). - operationId: getConfig - tags: - - .well-known - responses: - '200': - description: 'Hanko configuration' - content: - application/json: - schema: - $ref: '#/components/schemas/HankoConfiguration' - /saml/provider: - get: - deprecated: true - summary: Get a SAML provider - description: Get a SAML service provider config for a provided domain. - operationId: get-saml-provider - tags: - - SAML - parameters: - - name: domain - in: query - description: Fully qualified domain name for which a SAML service provider is registered - required: true - schema: - type: string - format: hostname - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - additionalProperties: false - properties: - enabled: - type: boolean - readOnly: true - default: true - name: - type: string - readOnly: true - example: MySamlProvier - domain: - type: string - format: hostname - readOnly: true - example: text.example - metadata_url: - type: string - format: uri - readOnly: true - example: 'http://idp-metadata.url' - skip_email_verification: - type: boolean - readOnly: true - default: false - attribute_map: - type: object - additionalProperties: false - properties: - name: - type: string - family_name: - type: string - given_name: - type: string - middle_name: - type: string - nickname: - type: string - preferred_username: - type: string - profile: - type: string - picture: - type: string - website: - type: string - gender: - type: string - birthdate: - type: string - zone_info: - type: string - locale: - type: string - updated_at: - type: string - email: - type: string - email_verified: - type: string - phone: - type: string - phone_verified: - type: string - '400': - $ref: '#/components/responses/BadRequest' - '404': - description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/JSONWebKeySet' + '500': + $ref: '#/components/responses/InternalServerError' /saml/metadata: get: summary: Get SAML Metadata @@ -747,470 +161,144 @@ paths: description: Temporary Redirect headers: Location: - schema: - type: string - description: 'On error, redirect to the `saml.default_redirect_url` set in the backend-configuration. Error details are provided in the location URL in the form of `error` and `error_description`query params.' - /sessions/validate: - get: - tags: - - Session Management - summary: Validate a session - description: | - Validate a session using a cookie header or an authorization header. - This is a passive check that does not update the session's internal last activity timestamp. - security: - - CookieAuth: [ ] - - BearerTokenAuth: [ ] - responses: - '200': - $ref: "#/components/responses/ValidateSessionResponse" - '400': - $ref: "#/components/responses/BadRequest" - '500': - $ref: '#/components/responses/InternalServerError' - post: - tags: - - Session Management - summary: Validate a session - description: | - Validate a session using a session token in a request body. - This endpoint updates the session's internal last activity timestamp. This extends the idle timeout window - if configured). - requestBody: - content: - application/json: - schema: - properties: - session_token: - description: The session token (JWT) to validate - type: string - format: JWT - required: - - session_token - responses: - '200': - $ref: "#/components/responses/ValidateSessionResponse" - '400': - $ref: "#/components/responses/BadRequest" - '500': - $ref: '#/components/responses/InternalServerError' - /thirdparty/auth: - get: - deprecated: true - summary: 'Initialize third party login' - description: | - Initialize an OAuth-backed (authorization code grant type) login with a third party provider by redirecting to - the specified provider login URL to retrieve an authorization code. - operationId: thirdPartyAuth - tags: - - Third Party - parameters: - - in: query - name: provider - required: true - schema: - type: string - enum: - - google - - github - description: | - The name of the third party provider to log in with. Only providers enabled in the - [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) - via the `thirdparty.providers` option can be used. Requesting an unsupported provider results in a - redirect with error details in the location query. - - in: query - name: redirect_to - required: true - schema: - type: string - format: base64url - description: | - Base64url encoded string representing the URL the - [`/callback`](#tag/Third-Party/operation/thirdPartyCallback) eventually redirects to after successful login - with the third party provider. It must match one of the allowed redirect URLs set in the backend - [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) - through the `third_party.allowed_redirect_urls`. - responses: - '307': - description: 'Redirect to third party provider' - headers: - Location: - schema: - type: string - description: | - Redirect to the third party provider on success. On error, redirects to the `Referer`. If `Referer` is - not present, redirects to the `third_party.error_redirect_url` set in the backend - [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config). - Error details are provided in the location URL in the form of `error` and `error_description` - query params. - /thirdparty/callback: - get: - summary: 'Third party provider callback' - description: Callback endpoint called by the third party provider after successful login. - operationId: thirdPartyCallback - tags: - - Third Party - parameters: - - in: query - name: code - schema: - type: string - description: | - The authorization code that can be exchanged for an access token and to retrieve user provider data - - in: query - name: state - required: true - schema: - type: string - description: The state - - in: query - name: error - schema: - type: string - description: | - An error returned from the third party provider - - in: query - name: error_description - schema: - type: string - description: The description of the error that occurred (if any) - responses: - '307': - description: 'Redirect to requested redirect URL or to configured site redirect URL' - headers: - Location: - schema: - type: string - description: | - Redirect to the URL requested via `redirect_to` query parameter during third party - provider login via [`/auth`](#tag/Third-Party/operation/thirdPartyAuth) endpoint on success. On error, - redirect to the `third_party.error_redirect_url` set in the backend - [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config). - Error details are provided in the location URL in the form of `error` and `error_description` - query params. - X-Auth-Token: - description: | - Present only on successful callback and when enabled via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.enable_auth_token_header` - for purposes of cross-domain communication between client and Hanko API. - schema: - $ref: '#/components/schemas/X-Auth-Token' - Set-Cookie: - description: | - Present only on successful callback. Contains the JSON Web Token (JWT) that must be provided to protected endpoints. - Cookie attributes (e.g. domain) can be set via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.cookie`. - schema: - $ref: '#/components/schemas/CookieSession' - /token: - post: - deprecated: true - summary: 'Exchange one time token for session' - description: | - Provide a one time token (e.g. obtained through the [thirdparty callback](#tag/Third-Party/operation/thirdPartyCallback)) to retrieve a session JWT as cookie - and/or via `X-Auth-Token` header. - operationId: token - tags: - - Token - requestBody: - content: - application/json: - schema: - type: object - properties: - value: - type: string - format: base64url - responses: - '200': - description: Successful token exchange - headers: - X-Auth-Token: - description: | - Present only on successful exchange and when enabled via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.enable_auth_token_header` - for purposes of cross-domain communication between client and Hanko API. - schema: - $ref: '#/components/schemas/X-Auth-Token' - X-Session-Lifetime: - description: | - Contains the seconds until the session expires. - schema: - $ref: '#/components/schemas/X-Session-Lifetime' - Set-Cookie: - description: | - Present only on successful exchange. Contains the JSON Web Token (JWT) that must be provided to protected endpoints. - Cookie attributes (e.g. domain) can be set via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.cookie`. - schema: - $ref: '#/components/schemas/CookieSession' - content: - application/json: - schema: - type: object - properties: - user_id: - description: The ID of the user on whose behalf the token was exchanged. - allOf: - - $ref: '#/components/schemas/UUID4' - '400': - $ref: '#/components/responses/BadRequest' - '404': - $ref: '#/components/responses/NotFound' - '422': - $ref: '#/components/responses/unprocessableEntity' - '429': - $ref: '#/components/responses/TooManyRequests' - /user: - post: - deprecated: true - summary: 'Get user details by email' - description: Retrieve details for user corresponding to the given `email`. - operationId: getUserId - tags: - - User Management - requestBody: - content: - application/json: - schema: - type: object - properties: - email: - type: string - format: email - responses: - '200': - description: 'User' - content: - application/json: - schema: - type: object - properties: - id: - $ref: '#/components/schemas/UUID4' - email_id: - $ref: '#/components/schemas/UUID4' - verified: - type: boolean - has_webauthn_credential: - type: boolean - '400': - $ref: '#/components/responses/BadRequest' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServerError' - delete: - deprecated: true - summary: 'Deletes the current user' - description: Used to delete the current user. Note that `config.account.allow_deletion` must be set to true. - operationId: deleteUser - tags: - - User Management - security: - - CookieAuth: [ ] - - BearerTokenAuth: [ ] - responses: - '204': - description: 'The user has been deleted' - '401': - $ref: '#/components/responses/Unauthorized' - '500': - $ref: '#/components/responses/InternalServerError' - /me: - get: - summary: 'Get the current user' - description: Retrieve data for the current user (i.e. the subject of the JWT given in a cookie or as a bearer token). - operationId: IsUserAuthorized - tags: - - User Management - security: - - CookieAuth: [ ] - - BearerTokenAuth: [ ] - responses: - '200': - $ref: '#/components/responses/MeResponse' - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/Unauthorized' - '500': - $ref: '#/components/responses/InternalServerError' - /logout: - post: - summary: "Log out the current user" - description: "Logs out the user by removing the authorization cookie." - operationId: logout - tags: - - User Management - security: - - CookieAuth: [ ] - - BearerTokenAuth: [ ] - responses: - '204': - description: 'The user has been logged out' - '401': - $ref: '#/components/responses/Unauthorized' - '500': - $ref: '#/components/responses/InternalServerError' - /users: - post: - deprecated: true - summary: 'Create a user' - description: Used to create a new user. To disable this endpoint, `config.account.allow_signup` must be set to false. - operationId: createUser - tags: - - User Management - requestBody: - content: - application/json: - schema: - type: object - properties: - email: - type: string - format: email - required: - - email - responses: - '200': - description: 'Details about the created user' - content: - application/json: - schema: - $ref: '#/components/schemas/CreateUserResponseObject' - '400': - $ref: '#/components/responses/BadRequest' - '403': - $ref: '#/components/responses/Forbidden' - '409': - $ref: '#/components/responses/Conflict' - '500': - $ref: '#/components/responses/InternalServerError' - /users/{id}: + schema: + type: string + description: 'On error, redirect to the `saml.default_redirect_url` set in the backend-configuration. Error details are provided in the location URL in the form of `error` and `error_description`query params.' + /sessions/validate: get: - summary: 'Get a user by ID' - operationId: listUser - deprecated: true tags: - - User Management + - Session Management + summary: Validate a session + description: | + Validate a session using a cookie header or an authorization header. + This is a passive check that does not update the session's internal last activity timestamp. security: - CookieAuth: [ ] - BearerTokenAuth: [ ] - parameters: - - name: id - in: path - description: ID of the user - required: true - schema: - $ref: '#/components/schemas/UUID4' responses: '200': - $ref: '#/components/responses/GetUserByIdResponse' + $ref: "#/components/responses/ValidateSessionResponse" '400': - $ref: '#/components/responses/BadRequest' - '403': - $ref: '#/components/responses/Forbidden' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServerError' - /emails: - get: - summary: 'Get a list of emails of the current user.' - operationId: listEmails - tags: - - Email Management - deprecated: true - security: - - CookieAuth: [ ] - - BearerTokenAuth: [ ] - responses: - '200': - description: 'A list of emails assigned to the current user' - content: - application/json: - schema: - $ref: '#/components/schemas/Emails' - '401': - $ref: '#/components/responses/Unauthorized' + $ref: "#/components/responses/BadRequest" '500': $ref: '#/components/responses/InternalServerError' post: - deprecated: true - summary: 'Add a new email address to the current user.' - operationId: createEmail tags: - - Email Management - security: - - CookieAuth: [ ] - - BearerTokenAuth: [ ] + - Session Management + summary: Validate a session + description: | + Validate a session using a session token in a request body. + This endpoint updates the session's internal last activity timestamp. This extends the idle timeout window + if configured). requestBody: content: application/json: schema: - type: object properties: - address: + session_token: + description: The session token (JWT) to validate type: string - format: email + format: JWT required: - - address + - session_token responses: - '201': - description: 'Email successfully added' + '200': + $ref: "#/components/responses/ValidateSessionResponse" '400': - $ref: '#/components/responses/BadRequest' - '409': - $ref: '#/components/responses/Conflict' + $ref: "#/components/responses/BadRequest" '500': $ref: '#/components/responses/InternalServerError' - /emails/{id}/set_primary: - post: - deprecated: true - summary: 'Marks the email address as primary email' - operationId: setPrimaryEmail + /thirdparty/callback: + get: + summary: 'Third party provider callback' + description: Callback endpoint called by the third party provider after successful login. + operationId: thirdPartyCallback tags: - - Email Management - security: - - CookieAuth: [ ] - - BearerTokenAuth: [ ] + - Third Party parameters: - - name: id - in: path - description: ID of the email address + - in: query + name: code + schema: + type: string + description: | + The authorization code that can be exchanged for an access token and to retrieve user provider data + - in: query + name: state required: true schema: - $ref: '#/components/schemas/UUID4' + type: string + description: The state + - in: query + name: error + schema: + type: string + description: | + An error returned from the third party provider + - in: query + name: error_description + schema: + type: string + description: The description of the error that occurred (if any) + responses: + '307': + description: 'Redirect to requested redirect URL or to configured site redirect URL' + headers: + Location: + schema: + type: string + description: | + Redirect to the URL requested via `redirect_to` query parameter during third party + provider login via [`/auth`](#tag/Third-Party/operation/thirdPartyAuth) endpoint on success. On error, + redirect to the `third_party.error_redirect_url` set in the backend + [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config). + Error details are provided in the location URL in the form of `error` and `error_description` + query params. + X-Auth-Token: + description: | + Present only on successful callback and when enabled via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.enable_auth_token_header` + for purposes of cross-domain communication between client and Hanko API. + schema: + $ref: '#/components/schemas/X-Auth-Token' + Set-Cookie: + description: | + Present only on successful callback. Contains the JSON Web Token (JWT) that must be provided to protected endpoints. + Cookie attributes (e.g. domain) can be set via [configuration](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) option `session.cookie`. + schema: + $ref: '#/components/schemas/CookieSession' + /me: + get: + summary: 'Get the current user' + description: Retrieve data for the current user (i.e. the subject of the JWT given in a cookie or as a bearer token). + operationId: IsUserAuthorized + tags: + - User Management + security: + - CookieAuth: [ ] + - BearerTokenAuth: [ ] responses: - '201': - description: 'Email has been set as primary' + '200': + $ref: '#/components/responses/MeResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalServerError' - /emails/{id}: - delete: - deprecated: true - summary: 'Delete an email address' - operationId: deleteEmail + /logout: + post: + summary: "Log out the current user" + description: "Logs out the user by removing the authorization cookie." + operationId: logout tags: - - Email Management + - User Management security: - CookieAuth: [ ] - BearerTokenAuth: [ ] - parameters: - - name: id - in: path - description: ID of the email address - required: true - schema: - $ref: '#/components/schemas/UUID4' responses: - '201': - description: 'Email has been deleted' + '204': + description: 'The user has been logged out' '401': $ref: '#/components/responses/Unauthorized' - '409': - $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalServerError' components: @@ -1227,25 +315,6 @@ components: properties: username: $ref: '#/components/schemas/Username' - GetUserByIdResponse: - description: Details for a user retrieved by ID - content: - application/json: - schema: - type: object - allOf: - - $ref: '#/components/schemas/UserBase' - - type: object - properties: - email: - description: The email address of the user - type: string - format: email - username: - description: The username of the user - type: string - webauthn_credentials: - $ref: '#/components/schemas/WebauthnCredentials' ValidateSessionResponse: description: Session validation response content: @@ -1366,172 +435,10 @@ components: code: 422 message: Unprocessable Entity schemas: - HankoConfiguration: - description: Public backend configuration options - type: object - externalDocs: - description: Hanko Configuration - url: https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md - properties: - emails: - description: Controls the behavior regarding email addresses. - type: object - properties: - require_verification: - description: Require email verification after account registration and prevent signing in with unverified email addresses. Also, email addresses can only be marked as primary when they have been verified before. - type: boolean - password: - description: Configuration options concerning passwords - type: object - properties: - enabled: - description: Indicates whether passwords are enabled or not - type: boolean - min_password_length: - description: Describes the minimum password length - type: number - example: 8 - account: - description: Controls the behavior regarding user account. - type: object - properties: - allow_deletion: - description: Indicates the user account can be deleted by the current user. - type: boolean - allow_signup: - description: Indicates users are able to create new accounts. - type: boolean CookieSession: type: string description: Value `` is a [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519.html) example: hanko=; Path=/; HttpOnly - CredentialCreationOptions: - description: "Options for credential creation with the WebAuthn API" - externalDocs: - url: https://www.w3.org/TR/webauthn-2/#dictionary-makecredentialoptions - type: object - properties: - publicKey: - type: object - properties: - rp: - type: object - properties: - name: - type: string - example: Hanko Authentication Service - id: - type: string - example: localhost - user: - type: object - properties: - id: - type: string - example: pPQT9rwJRD7gVncsnCDNyN - name: - type: string - example: user@example.com - displayName: - type: string - example: user@example.com - challenge: - type: string - format: base64url - example: 7qmkJUXR0dOFnsW48evX3qKdCzlGjvvqAAvMDN+KTN0= - pubKeyCredParams: - type: array - items: - type: object - properties: - type: - type: string - enum: - - public-key - alg: - type: number - example: - - type: public-key - alg: -7 - timeout: - type: integer - format: int64 - example: 60000 - authenticatorSelection: - type: object - properties: - authenticatorAttachment: - type: string - enum: - - platform - - cross-platform - example: platform - requireResidentKey: - type: boolean - example: true - residentKey: - type: string - enum: - - discouraged - - preferred - - required - example: preferred - userVerification: - type: string - enum: - - discouraged - - preferred - - required - example: required - attestation: - type: string - enum: - - none - - indirect - - direct - - enterprise - example: none - CredentialRequestOptions: - description: "Options for assertion generation with the WebAuthn API" - externalDocs: - url: https://www.w3.org/TR/webauthn-2/#dictionary-assertion-options - type: object - properties: - publicKey: - type: object - properties: - challenge: - type: string - format: base64url - example: qgOI+0KpGnl9NOqaT6dfsYvi96R87LgpErnvePeOgSU= - timeout: - type: integer - format: int64 - example: 60000 - rpId: - type: string - example: localhost - allowCredentials: - type: array - items: - type: object - properties: - type: - type: string - enum: - - public-key - example: public-key - id: - type: string - format: base64url - example: Mepptysj5ZZrTlg0qiLbsZ068OtQMeGVAikVy2n1hvvG... - userVerification: - type: string - enum: - - required - - preferred - - discouraged - example: required Identity: type: object description: Representation of a user's third party connection/identity. @@ -1609,145 +516,6 @@ components: externalDocs: description: RFC7517 - JSON Web Key (JWK) - Section 5 url: https://www.rfc-editor.org/rfc/rfc7517#section-5 - Passcode: - description: Representation of a passcode - type: object - properties: - id: - description: The ID of the passcode - allOf: - - $ref: '#/components/schemas/UUID4' - ttl: - type: integer - description: Lifespan of a passcode in seconds - example: 300 - created_at: - description: Time of creation of the passcode - type: string - format: date-time - Password: - description: | - The actual password, its `minLength` defaults to 8 but - can be [configured](https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config) - through the `password.min_password_length` option. - type: string - minLength: 8 - maxLength: 72 - example: 9UnCBEx924a45P7p - PublicKeyCredentialAssertionResponse: - description: 'WebAuthn API response to a navigator.credentials.get() call' - type: object - properties: - id: - type: string - example: _18q6IjW09tiM4NSbsZjocUtGx00Muv5mN6LZCelCMDD... - rawId: - type: string - example: _18q6IjW09tiM4NSbsZjocUtGx00Muv5mN6LZCelCMDD... - type: - type: string - enum: - - public-key - example: public-key - response: - type: object - properties: - clientDataJson: - type: string - format: base64url - example: eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdl... - authenticatorData: - type: string - format: base64url - example: SZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2MF... - signature: - type: string - format: base64url - example: MEQCIHe2RXqh6dyZw1LNXgeTTxljCV_qK2ydQjp02CiF... - userHandle: - type: string - format: base64url - example: rpe_EkgaSEeZG0TwzZyZJw - PublicKeyCredentialAttestationResponse: - description: 'WebAuthn API response to a navigator.credentials.create() call' - type: object - properties: - id: - type: string - example: _18q6IjW09tiM4NSbsZjocUtGx00Muv5mN6LZCelCMDD... - rawId: - type: string - example: _18q6IjW09tiM4NSbsZjocUtGx00Muv5mN6LZCelCMDD... - type: - type: string - enum: - - public-key - example: public-key - response: - type: object - properties: - clientDataJson: - type: string - format: base64url - example: eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdl... - attestationObject: - type: string - format: base64url - example: o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YVjfSZYN... - transports: - type: array - items: - type: string - enum: - - usb - - nfc - - ble - - internal - example: internal - GetUserResponse: - type: object - properties: - id: - description: The ID of the user - allOf: - - $ref: '#/components/schemas/UUID4' - email: - description: The email address of the user - type: string - format: email - created_at: - description: Time of creation of the the user - type: string - format: date-time - updated_at: - description: Time of last update of the user - type: string - format: date-time - verified: - description: Indicates whether the user's email address was verified - type: boolean - webauthn_credentials: - description: List of registered Webauthn credentials - type: array - items: - type: object - properties: - id: - description: The ID of the Webauthn credential - type: string - format: base64url - example: Meprtysj5ZZrTlg0qiLbsZ168OtQMeGVAikVy2n1hvvG... - CreateUserResponseObject: - type: object - properties: - user_id: - description: "The ID of the newly created user" - allOf: - - $ref: '#/components/schemas/UUID4' - email_id: - description: "The ID of the newly created email address" - allOf: - - $ref: '#/components/schemas/UUID4' JWTClaims: type: object description: "The claims extracted from a JWT." @@ -2035,16 +803,6 @@ components: backup_eligible: true backup_state: false mfa_only: true - WebauthnLoginResponse: - description: 'Response after a successful login with webauthn' - type: object - properties: - credential_id: - type: string - format: base64url - user_id: - type: string - format: uuid4 UUID4: type: string format: uuid4 @@ -2068,10 +826,6 @@ components: format: JWT externalDocs: url: https://github.com/teamhanko/hanko/blob/main/backend/docs/Config.md#hanko-backend-config - X-Session-Lifetime: - description: | - Contains the seconds until the session expires. - type: number securitySchemes: CookieAuth: type: apiKey