API Scopes (OAuth)

OAuth-style API scope contracts that map to internal permissions. API scopes provide a higher-level abstraction for client-facing authorization, bundling multiple internal permissions into named scopes.

Admin Endpoints

List API Scopes (Admin)

Returns all API scopes for the tenant from the primary admin database with permission counts.

Endpoint: GET /uflow/admin/api_scopes

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer JWT token

Query Parameters

Parameter	Type	Required	Description
name	string	No	Filter by scope name (partial match)

Response

Success (200):

[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "permissions_linked": 0,
    "created_at": "string"
  }
]

Error Responses:

• 401 - Unauthorized
• 500 - Internal Server Error

---

Create API Scope (Admin)

Creates an OAuth scope contract and maps it to internal permissions. Transaction: 1) insert into api_scopes, 2) insert into api_scope_permissions.

Endpoint: POST /uflow/admin/api_scopes

Request Body

{
  "name": "string",
  "description": "string",
  "permission_ids": ["string"]
}

Parameters

Parameter	Type	Required	Description
name	string	Yes	Scope name
description	string	No	Scope description
permission_ids	array[string]	No	Internal permission IDs to link

Response

Success (200):

{
  "id": "string",
  "name": "string",
  "description": "string",
  "permission_ids": ["string"],
  "permissions_count": 0,
  "created_at": "string"
}

Error Responses:

• 400 - Invalid request or permission validation failed
• 401 - Unauthorized
• 409 - Scope name already exists
• 500 - Internal Server Error

---

Get API Scope Details (Admin)

Returns a single API scope with its linked permission details.

Endpoint: GET /uflow/admin/api_scopes/{scope_id}

Path Parameters

Parameter	Type	Required	Description
scope_id	string	Yes	Scope ID (UUID)

Response

Success (200):

{
  "id": "string",
  "name": "string",
  "description": "string",
  "permission_ids": ["string"],
  "permissions_count": 0,
  "created_at": "string"
}

Error Responses:

• 400 - Invalid scope ID
• 401 - Unauthorized
• 404 - Scope not found

---

Update API Scope (Admin)

Updates an API scope and replaces permission mappings. Transaction: 1) update api_scopes, 2) delete + insert api_scope_permissions.

Endpoint: PUT /uflow/admin/api_scopes/{scope_id}

Path Parameters

Parameter	Type	Required	Description
scope_id	string	Yes	Scope ID (UUID)

Request Body

{
  "name": "string",
  "description": "string",
  "permission_ids": ["string"]
}

Response

Success (200):

{
  "id": "string",
  "name": "string",
  "description": "string",
  "permission_ids": ["string"],
  "permissions_count": 0
}

Error Responses:

• 400 - Invalid request
• 401 - Unauthorized
• 404 - Scope not found
• 409 - Scope name already exists
• 500 - Internal Server Error

---

Delete API Scope (Admin)

Deletes an API scope and all permission mappings (cascade).

Endpoint: DELETE /uflow/admin/api_scopes/{scope_id}

Path Parameters

Parameter	Type	Required	Description
scope_id	string	Yes	Scope ID (UUID)

Response

Success (200):

{
  "message": "string"
}

Error Responses:

• 400 - Invalid scope ID
• 401 - Unauthorized
• 404 - Scope not found
• 500 - Internal Server Error

---

End-User Endpoints

List API Scopes (End User)

Returns all API scopes from the tenant database with permission counts.

Endpoint: GET /uflow/user/api_scopes

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer JWT token

Query Parameters

Parameter	Type	Required	Description
name	string	No	Filter by scope name (partial match)

Response

Success (200):

[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "permissions_linked": 0,
    "created_at": "string"
  }
]

Error Responses:

• 401 - Unauthorized
• 500 - Internal Server Error

---

Create API Scope (End User)

Creates an OAuth scope contract in the tenant database and maps it to internal permissions.

Endpoint: POST /uflow/user/api_scopes

Request Body

{
  "name": "string",
  "description": "string",
  "permission_ids": ["string"]
}

Response

Success (200):

{
  "id": "string",
  "name": "string",
  "description": "string",
  "permission_ids": ["string"],
  "permissions_count": 0,
  "created_at": "string"
}

Error Responses:

• 400 - Invalid request or permission validation failed
• 401 - Unauthorized
• 409 - Scope name already exists
• 500 - Internal Server Error

---

Get API Scope Details (End User)

Returns a single API scope with its linked permission details from the tenant database.

Endpoint: GET /uflow/user/api_scopes/{scope_id}

Path Parameters

Parameter	Type	Required	Description
scope_id	string	Yes	Scope ID (UUID)

Response

Success (200):

{
  "id": "string",
  "name": "string",
  "description": "string",
  "permission_ids": ["string"],
  "permissions_count": 0,
  "created_at": "string"
}

Error Responses:

• 400 - Invalid scope ID
• 401 - Unauthorized
• 404 - Scope not found

---

Update API Scope (End User)

Updates an API scope and replaces permission mappings in the tenant database.

Endpoint: PUT /uflow/user/api_scopes/{scope_id}

Path Parameters

Parameter	Type	Required	Description
scope_id	string	Yes	Scope ID (UUID)

Request Body

{
  "name": "string",
  "description": "string",
  "permission_ids": ["string"]
}

Response

Success (200):

{
  "id": "string",
  "name": "string",
  "description": "string",
  "permission_ids": ["string"],
  "permissions_count": 0
}

Error Responses:

• 400 - Invalid request
• 401 - Unauthorized
• 404 - Scope not found
• 409 - Scope name already exists
• 500 - Internal Server Error

---

Delete API Scope (End User)

Deletes an API scope and all permission mappings (cascade) from the tenant database.

Endpoint: DELETE /uflow/user/api_scopes/{scope_id}

Path Parameters

Parameter	Type	Required	Description
scope_id	string	Yes	Scope ID (UUID)

Response

Success (200):

{
  "message": "string"
}

Error Responses:

• 400 - Invalid scope ID
• 401 - Unauthorized
• 404 - Scope not found
• 500 - Internal Server Error