Applications API

Application management endpoints are provided through the dashboard API and use Sanctum session cookie authentication (not JWT). These endpoints are intended for use by the YorAuth dashboard, though they can be consumed directly with a valid Sanctum session.

Authentication

All dashboard endpoints require Sanctum cookie authentication. Login via POST /api/dashboard/login to establish a session.

List Applications

GET /api/dashboard/applications

List all applications accessible to the authenticated platform admin. Returns applications the user owns or has been granted access to via organization membership.

Query Parameters

Parameter	Type	Description
`organization_id`	string (UUID)	Filter by organization

Response

200 OK

json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "My Production App",
      "environment": "production",
      "is_test_mode": false,
      "description": "Main customer-facing application",
      "organization_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "role": "owner",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-02-25T12:00:00Z"
    }
  ]
}

Create Application

POST /api/dashboard/applications

Create a new application. Subject to plan-based application limits.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Application name. Max 255 characters.
`environment`	string	No	`development`, `staging`, or `production`. Defaults to `development`.
`is_test_mode`	boolean	No	Enable test mode. Defaults to `false`.
`description`	string	No	Optional description. Max 1000 characters.
`organization_id`	string (UUID)	No	Associate with an organization. Required if you belong to multiple organizations.

Response

201 Created

json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "My New App",
    "environment": "development",
    "is_test_mode": false,
    "description": null,
    "organization_id": null,
    "created_at": "2026-02-25T12:00:00Z"
  }
}

Error Responses

Status	Code	Description
403	`resource_limit_exceeded`	Application limit reached for current plan
403	`FORBIDDEN`	Insufficient organization permissions
422	`VALIDATION_ERROR`	`organization_id` required when user belongs to multiple organizations

Get Application

GET /api/dashboard/applications/{applicationId}

Retrieve full details of a single application including branding configuration.

Response

200 OK

json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "My Production App",
    "environment": "production",
    "is_test_mode": false,
    "description": "Main customer-facing application",
    "role": "owner",
    "brand_name": "Acme Corp",
    "brand_logo_url": "https://example.com/logo.png",
    "brand_color": "#1a73e8",
    "brand_background": "#ffffff",
    "branding_options": {
      "secondary_color": "#fbbc04",
      "font_family": "Inter",
      "button_border_radius": "8px"
    },
    "oauth_redirect_uris": ["https://app.example.com/callback"],
    "oauth_hosted_login_enabled": true,
    "max_concurrent_sessions": 5,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-02-25T12:00:00Z"
  }
}

Update Application

PUT /api/dashboard/applications/{applicationId}

Update application settings. All fields are optional.

Request Body

Field	Type	Required	Description
`name`	string	No	Application name
`environment`	string	No	`development`, `staging`, or `production`
`is_test_mode`	boolean	No	Enable or disable test mode
`description`	string	No	Application description
`oauth_hosted_login_enabled`	boolean	No	Enable the YorAuth hosted login UI
`oauth_redirect_uris`	array of strings	No	Allowed OAuth redirect URIs
`max_concurrent_sessions`	integer	No	Max concurrent sessions per user. `0` means unlimited. Max 100.

Response

200 OK

json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "My Updated App",
    "environment": "production",
    "is_test_mode": false,
    "description": "Updated description",
    "oauth_hosted_login_enabled": true,
    "oauth_redirect_uris": ["https://app.example.com/callback"],
    "max_concurrent_sessions": 10,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-02-25T14:00:00Z"
  }
}

Update Branding

PUT /api/dashboard/applications/{applicationId}/branding

Update the visual branding for hosted login pages and consent screens.

Request Body

Field	Type	Required	Description
`brand_name`	string	No	Brand name shown on hosted pages
`brand_logo_url`	string (URL)	No	Logo image URL
`brand_color`	string	No	Primary brand color as a hex code (e.g., `#1a73e8`)
`brand_background`	string	No	Background color as a hex code
`branding_options`	object	No	Extended branding options (see below)
`branding_options.secondary_color`	string	No	Secondary brand color
`branding_options.font_family`	string	No	Font family name
`branding_options.favicon_url`	string (URL)	No	Favicon URL
`branding_options.button_border_radius`	string	No	CSS border-radius value (e.g., `8px`, `50%`)
`branding_options.custom_css`	string	No	Custom CSS injected into hosted pages. Max 5000 characters. Sanitized server-side.
`branding_options.dark_mode.enabled`	boolean	No	Enable dark mode
`branding_options.dark_mode.background`	string	No	Dark mode background color
`branding_options.dark_mode.color`	string	No	Dark mode foreground color

Response

200 OK

json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "My App",
    "brand_name": "Acme Corp",
    "brand_logo_url": "https://example.com/logo.png",
    "brand_color": "#1a73e8",
    "brand_background": "#ffffff",
    "branding_options": {
      "font_family": "Inter",
      "button_border_radius": "8px",
      "dark_mode": {
        "enabled": true,
        "background": "#121212",
        "color": "#ffffff"
      }
    },
    "branding": {
      "name": "Acme Corp",
      "logo_url": "https://example.com/logo.png",
      "color": "#1a73e8",
      "background": "#ffffff"
    }
  }
}

Delete Application

DELETE /api/dashboard/applications/{applicationId}

Permanently delete an application and all associated data.

This action is irreversible. All users, roles, permissions, API keys, and webhooks associated with the application will be deleted.

Response

204 No Content