API reference
Sign-in API
Browser sign-in with a configured provider, and sign-out.
- List sign-in methods:
GET /v1/auth/providers - Start browser sign-in:
GET /v1/auth/login - Complete browser sign-in:
GET /v1/auth/callback - Sign out:
POST /v1/auth/logout
List sign-in methods
GET /v1/auth/providers
The sign-in methods this service offers and its access mode, for the sign-in page. Unauthenticated.
- Authentication: none on this route.
- Who: No authentication.
Responses
| Status | Description | Body |
|---|---|---|
200 | — | SignInProvidersDto |
curl "$VMYARD_API_URL/v1/auth/providers"{
"access": "open",
"providers": [
{
"default": false,
"display_name": "string",
"kind": "oidc",
"name": "dev"
}
],
"waitlist_url": "string"
}Start browser sign-in
GET /v1/auth/login
- Authentication: none on this route.
- Who: No authentication.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
provider | query | string | No | Configured sign-in method such as google or github; omitted selects the default provider. |
return_to | query | string | No | Same-origin UI path (single leading /, at most 2048 bytes) to open after sign-in; invalid values become /. |
Responses
| Status | Description | Body |
|---|---|---|
303 | Redirect to <ui>/sign-in?error=unsupported_provider|oidc_unavailable|oidc_failed | — |
307 | Redirect to the selected OIDC provider | — |
curl "$VMYARD_API_URL/v1/auth/login"Complete browser sign-in
GET /v1/auth/callback
- Authentication: none on this route.
- Who: No authentication.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
code | query | string | No | |
state | query | string | No | |
error | query | string | No | OAuth error from the provider; access_denied maps to the access_denied sign-in error. |
Responses
| Status | Description | Body |
|---|---|---|
303 | Signed in (or, for a linking attempt, identity linked): redirect to the stored return_to on the UI origin. Failure: redirect to <ui>/sign-in?error=access_denied|identity_in_use|oidc_failed|oidc_unavailable|session_expired|unsupported_provider | — |
500 | Internal error (internal_error); quote the correlation_id. | ProblemDetails |
curl "$VMYARD_API_URL/v1/auth/callback"Sign out
POST /v1/auth/logout
Ends the browser session. API keys cannot sign out; revoke the key instead.
- API key: not accepted (
403 session_required). - Browser session: the
vmyard_sessioncookie and thex-csrf-tokenheader. - Who: The signed-in user.
Responses
| Status | Description | Body |
|---|---|---|
204 | Session revoked | — |
401 | Not signed in, or the API key is malformed, expired, or revoked (unauthenticated, invalid_api_key). | ProblemDetails |
403 | Missing or invalid CSRF token, or a bearer API key (session_required) | ProblemDetails |
curl -X POST "$VMYARD_API_URL/v1/auth/logout" \
-b "vmyard_session=$VMYARD_SESSION" \
-H "x-csrf-token: $VMYARD_CSRF"