Skip to main content

Endpoints & Discovery

Visual Passcodes defines several standard OpenID Connect (OIDC) endpoints that your application will interact with. You can dynamically discover these endpoints and other server capabilities using the .well-known configuration endpoint.

Issuer Authority​

The issuer authority is the base URL for all OIDC endpoints provided by Visual Passcodes. It uniquely identifies your tenant and serves as the foundation for constructing other endpoint URLs.

  • Issuer URL: https://your-server.com/api/oidc/{tenant_id}

Replace {tenant_id} with your specific tenant identifier. This URL is used in OIDC flows to validate tokens and discover endpoints.

Well-Known Discovery Endpoint​

By making a GET request to the discovery endpoint, a client can retrieve a JSON document containing the server's OIDC configuration. This allows clients to configure themselves dynamically, reducing the need for manual setup.

  • URL: https://your-server.com/api/oidc/{tenant_id}/.well-known/openid-configuration

The {tenant_id} placeholder must be replaced with the specific identifier for your tenant as provided by Visual Passcodes.

Key Endpoints​

The following key endpoints are defined in the discovery document and are used throughout the OIDC flows.

  • Authorization Endpoint: Used to initiate the authorization request and redirect the user for visual authentication.

    • https://your-server.com/api/oidc/{tenant_id}/authorize

  • Token Endpoint: Used by your application's backend to exchange an authorization_code for tokens.

    • https://your-server.com/api/oidc/{tenant_id}/token

  • JWKS (JSON Web Key Set) Endpoint: Returns Visual Passcodes' public signing keys in JWKS format. These keys are crucial for your application to verify the signature of ID tokens and access tokens.

    • https://your-server.com/api/oidc/{tenant_id}/.well-known/jwks

  • Userinfo Endpoint: A protected resource that returns standard claims about the authenticated user (e.g., name, email). Requires a valid access_token in the Authorization header.

    • https://your-server.com/api/userinfo

  • End Session Endpoint: Allows your application to initiate a logout sequence, terminating the user's session at Visual Passcodes.

    • https://your-server.com/api/auth/logout

  • Revocation Endpoint: Allows a client to revoke a previously issued access_token or refresh_token.

    • https://your-server.com/api/revoke