Resource

A resource is an instance of a resource type that represents an entity in your application. Resources can be workspaces, projects, apps, or any other object that users can access.

Resources are organized in a hierarchy. When a role is assigned to a user on a parent resource, they automatically gain access to child resources through permission inheritance.

List resources

Get a paginated list of authorization resources.

cURL

 curl "https://api.workos.com/authorization/resources" \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "object": "list",
  "data": [
    {
      "object": "authorization_resource",
      "name": "Website Redesign",
      "description": "Company website redesign project",
      "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
      "parent_resource_id": "authz_resource_01HXYZ123456789ABCDEFGHIJ",
      "id": "authz_resource_01HXYZ123456789ABCDEFGH",
      "external_id": "proj-456",
      "resource_type_slug": "project",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "list_metadata": {
    "before": "authz_resource_01HXYZ123456789ABCDEFGHIJ",
    "after": "authz_resource_01HXYZ987654321KJIHGFEDCBA"
  }
}

GET

`/authorization/resources`

`Parameters`

`Returns` `object`

Create a resource

Create a new authorization resource. The resource is associated with an organization and resource type.

You can optionally specify a parent resource to place it in a hierarchy. The parent can be identified either by parent_resource_id or by the combination of parent_resource_external_id and parent_resource_type_slug.

The external_id must be unique within the organization and resource type combination.

cURL

 curl --request POST \
  --url "https://api.workos.com/authorization/resources" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "external_id": "my-workspace-01",
        "name": "Acme Workspace",
        "resource_type_slug": "workspace",
        "organization_id": "org_01EHQMYV6MBK39QC5PZXHY59C3"
    }
BODY

 {
  "object": "authorization_resource",
  "name": "Acme Workspace",
  "description": "Primary workspace for the Acme team",
  "organization_id": "org_01EHQMYV6MBK39QC5PZXHY59C3",
  "parent_resource_id": "authz_resource_01HXYZ123456789ABCDEFGHIJ",
  "id": "authz_resource_01HXYZ123456789ABCDEFGH",
  "external_id": "my-workspace-01",
  "resource_type_slug": "workspace",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

POST

`/authorization/resources`

`Returns`

Get a resource

Retrieve the details of an authorization resource by its ID.

cURL

 curl "https://api.workos.com/authorization/resources/authz_resource_01HXYZ123456789ABCDEFGHIJ" \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "object": "authorization_resource",
  "name": "Website Redesign",
  "description": "Company website redesign project",
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "parent_resource_id": "authz_resource_01HXYZ123456789ABCDEFGHIJ",
  "id": "authz_resource_01HXYZ123456789ABCDEFGH",
  "external_id": "proj-456",
  "resource_type_slug": "project",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

GET

`/authorization/resources/:resource_id`

`Parameters`

`Returns`

Get a resource by external ID

Retrieve the details of an authorization resource by its external ID, organization, and resource type. This is useful when you only have the external ID from your system and need to fetch the full resource details.

cURL

 curl "https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/resources/project/proj-456" \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "object": "authorization_resource",
  "name": "Website Redesign",
  "description": "Company website redesign project",
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "parent_resource_id": "authz_resource_01HXYZ123456789ABCDEFGHIJ",
  "id": "authz_resource_01HXYZ123456789ABCDEFGH",
  "external_id": "proj-456",
  "resource_type_slug": "project",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

GET

`/authorization/organizations/:organization_id/resources/:resource_type_slug/:external_id`

`Parameters`

`Returns`

Update a resource

Update an existing authorization resource.

cURL

 curl --request PATCH \
  --url "https://api.workos.com/authorization/resources/authz_resource_01HXYZ123456789ABCDEFGHIJ" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "name": "Updated Name",
        "description": "Updated description",
        "parent_resource_id": "authz_resource_01HXYZ123456789ABCDEFGHIJ"
    }
BODY

 {
  "object": "authorization_resource",
  "name": "Updated Name",
  "description": "Updated description",
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "parent_resource_id": "authz_resource_01HXYZ123456789ABCDEFGHIJ",
  "id": "authz_resource_01HXYZ123456789ABCDEFGH",
  "external_id": "proj-456",
  "resource_type_slug": "project",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

PATCH

`/authorization/resources/:resource_id`

`Parameters`

`Returns`

Update a resource by external ID

Update an existing authorization resource using its external ID.

cURL

 curl --request PATCH \
  --url "https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/resources/project/proj-456" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "name": "Updated Name",
        "description": "Updated description",
        "parent_resource_external_id": "parent-workspace-01",
        "parent_resource_type_slug": "workspace"
    }
BODY

 {
  "object": "authorization_resource",
  "name": "Updated Name",
  "description": "Updated description",
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "parent_resource_id": "authz_resource_01HXYZ123456789ABCDEFGHIJ",
  "id": "authz_resource_01HXYZ123456789ABCDEFGH",
  "external_id": "proj-456",
  "resource_type_slug": "project",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

PATCH

`/authorization/organizations/:organization_id/resources/:resource_type_slug/:external_id`

`Parameters`

`Returns`

Delete a resource

Delete an authorization resource. By default, this will fail if the resource has child resources or role assignments. Set cascade_delete to true to delete the resource along with all its descendants and role assignments.

Deleting a resource also removes all role assignments on that resource. This action cannot be undone.

cURL

 curl --request DELETE \
  --url "https://api.workos.com/authorization/resources/authz_resource_01HXYZ123456789ABCDEFGHIJ" \
  --header "Authorization: Bearer sk_example_123456789"

DELETE

`/authorization/resources/:resource_id`

`Parameters`

`Returns`

Delete a resource by external ID

Delete an authorization resource using its external ID. By default, this will fail if the resource has child resources or role assignments. Set cascade_delete to true to delete the resource along with all its descendants and role assignments.

Deleting a resource also removes all role assignments on that resource. This action cannot be undone.

cURL

 curl --request DELETE \
  --url "https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/resources/project/proj-456" \
  --header "Authorization: Bearer sk_example_123456789"

DELETE

`/authorization/organizations/:organization_id/resources/:resource_type_slug/:external_id`

`Parameters`

`Returns`

Role assignment Continue to the next section

Up next

Resource

List resources

/authorization/resources

Parameters

before?: string

after?: string

limit?: integer

order?: "normal" | "desc" | "asc"

organization_id?: string

resource_type_slug?: string

resource_external_id?: string

parent_resource_id?: string

parent_resource_type_slug?: string

parent_external_id?: string

Returns object

object: "list"

data: object[]

list_metadata: object

Create a resource

/authorization/resources

external_id: string

name: string

description?: string

resource_type_slug: string

organization_id: string

parent_resource_id?: string

parent_resource_external_id?: string

parent_resource_type_slug?: string

Returns

authorization_resource: object

Get a resource

/authorization/resources/:resource_id

Parameters

resource_id: string

Returns

authorization_resource: object

Get a resource by external ID

/authorization/organizations/:organization_id/resources/:resource_type_slug/:external_id

Parameters

organization_id: string

resource_type_slug: string

external_id: string

Returns

authorization_resource: object

Update a resource

/authorization/resources/:resource_id

name?: string

description?: string

parent_resource_id?: string

parent_resource_external_id?: string

parent_resource_type_slug?: string

Parameters

resource_id: string

Returns

authorization_resource: object

Update a resource by external ID

/authorization/organizations/:organization_id/resources/:resource_type_slug/:external_id

name?: string

description?: string

parent_resource_id?: string

parent_resource_external_id?: string

parent_resource_type_slug?: string

Parameters

organization_id: string

resource_type_slug: string

external_id: string

Returns

authorization_resource: object

Delete a resource

/authorization/resources/:resource_id

Parameters

resource_id: string

cascade_delete?: boolean

Returns

empty: empty

Delete a resource by external ID

/authorization/organizations/:organization_id/resources/:resource_type_slug/:external_id

Parameters

organization_id: string

resource_type_slug: string

`/authorization/resources`

`Parameters`

`Returns` `object`

`/authorization/resources`

`Returns`

`/authorization/resources/:resource_id`

`Parameters`

`Returns`

`/authorization/organizations/:organization_id/resources/:resource_type_slug/:external_id`

`Parameters`

`Returns`

`/authorization/resources/:resource_id`

`Parameters`

`Returns`

`/authorization/organizations/:organization_id/resources/:resource_type_slug/:external_id`

`Parameters`

`Returns`

`/authorization/resources/:resource_id`

`Parameters`

`Returns`

`/authorization/organizations/:organization_id/resources/:resource_type_slug/:external_id`

`Parameters`

`Returns`