OAuth API

YorAuth provides OAuth 2.0 social login through the yorauth-gate microservice. The gate handles provider redirects and callbacks, then delivers the result back to the main API. The token exchange endpoint below is the application-side counterpart used after the gate flow completes.

Your application initiates OAuth by redirecting the user to the gate's authorize URL.
The gate redirects to the chosen provider (Google, GitHub, etc.).
The provider redirects back to the gate's callback URL.
The gate sends the result to the app's internal callback handler.
The app creates or links a user account and issues an authorization code.
Your application exchanges the code for tokens using the endpoint below.

OAuth Token Exchange

POST /oauth/token

Exchange an OAuth authorization code or refresh token for YorAuth access and refresh tokens. This is the standard OAuth 2.0 token endpoint for the hosted login flow.

Authorization Code Grant

Field	Type	Required	Description
`grant_type`	string	Yes	Must be `authorization_code`
`code`	string	Yes	The authorization code issued after OAuth callback
`redirect_uri`	string	Yes	The redirect URI used when initiating the flow
`code_verifier`	string	No	PKCE code verifier if PKCE was used

Response

200 OK

json

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "ref_a1b2c3d4...",
  "scope": "openid profile email"
}

Refresh Token Grant

Field	Type	Required	Description
`grant_type`	string	Yes	Must be `refresh_token`
`refresh_token`	string	Yes	A previously issued refresh token

Response

200 OK

json

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "ref_d4e5f6a7..."
}

Error Responses

Status	Error	Description
400	`unsupported_grant_type`	Grant type is not `authorization_code` or `refresh_token`
400	`invalid_request`	Required fields are missing
400	`invalid_grant`	Authorization code is invalid, expired, or already used
400	`invalid_grant`	Refresh token is invalid, expired, or revoked

OAuth Provider Configuration

OAuth providers are configured per application via the dashboard API. These endpoints use Sanctum cookie authentication.

List Configured Providers

GET /api/dashboard/applications/{applicationId}/providers/configured

List all OAuth providers that have been configured for the application.

Provider Marketplace

GET /api/dashboard/applications/{applicationId}/providers/marketplace

List all available OAuth providers that can be configured.

Configure Provider

POST /api/dashboard/applications/{applicationId}/providers/configure

Add an OAuth provider configuration for the application (e.g., set up Google OAuth with your client ID and secret).

Update Provider Configuration

PUT /api/dashboard/applications/{applicationId}/providers/{configId}

Update an existing provider configuration.

Delete Provider Configuration

DELETE /api/dashboard/applications/{applicationId}/providers/{configId}

Remove an OAuth provider from the application.

GET /api/dashboard/applications/{applicationId}/providers/{configId}/test-login-url

Get a test URL to verify that an OAuth provider configuration is working.

Get Callback URL

GET /api/dashboard/applications/{applicationId}/providers/{providerId}/callback-url

Retrieve the callback URL to register with the OAuth provider's developer console.

OAuth Connections

When a user connects an OAuth provider, a connection record is created. These can be managed via the dashboard API.

List Connections

GET /api/dashboard/applications/{applicationId}/connections

List all OAuth connections for an application.

Revoke Connection

POST /api/dashboard/applications/{applicationId}/connections/{connectionId}/revoke

Revoke an OAuth connection, invalidating the stored provider tokens.

The gate service (yorauth-gate) handles all OAuth redirect and callback traffic. It runs on port 8001 and exposes only web routes — it has no public API routes. All provider integrations are managed through the app API described above.