TenantRole

This document uses the REST API. For more details, see the Authentication for API page.

Create a custom tenant role for a given tenant (Early Access)

post

Create a custom tenant role for a given tenant.

Required permissions

• View Tenant Roles (tenant.roles.read)

• Create Tenant Roles (tenant.roles.create)

Authorizations

APITokenBearerAuth

AuthorizationstringRequired

API key value must be prefixed with "Token ".

Path parameters

tenant_idstring · uuidRequired

Unique identifier of the tenant.

Example: 00000000-0000-0000-0000-000000000000

Query parameters

versionstringRequired

Requested API version

Example: 2025-11-05Pattern: ^(wip|work-in-progress|experimental|beta|((([0-9]{4})-([0-1][0-9]))-((3[01])|(0[1-9])|([12][0-9]))(~(wip|work-in-progress|experimental|beta))?))$

Body

application/vnd.api+json

Responses

201

Tenant role successfully created.

application/vnd.api+json

400

Bad Request: A parameter provided as a part of the request was invalid.

application/vnd.api+json

401

Unauthorized: the request requires an authentication token.

application/vnd.api+json

403

Forbidden: the request requires an authentication token with more or different permissions.

application/vnd.api+json

404

Not Found: The resource being operated on could not be found.

application/vnd.api+json

409

Conflict: The requested operation conflicts with the current state of the resource in some way.

application/vnd.api+json

500

Internal Server Error: An error was encountered while attempting to process the request.

application/vnd.api+json

post

/tenants/{tenant_id}/roles

HTTPcURLJavaScriptPython

POST /rest/tenants/{tenant_id}/roles?version=2025-11-05 HTTP/1.1
Host: api.snyk.io
Authorization: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 104

{
  "data": {
    "attributes": {
      "description": "text",
      "name": "text",
      "permissions": [
        "text"
      ]
    },
    "type": "tenant_role"
  }
}

{
  "data": {
    "attributes": {
      "custom": false,
      "description": "text",
      "name": "text",
      "normalized_name": "text",
      "permissions": [
        "text"
      ]
    },
    "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
    "meta": {
      "app_count": 1,
      "service_account_count": 1,
      "user_count": 1
    },
    "relationships": {
      "tenant": {
        "data": {
          "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
          "type": "tenant"
        }
      }
    },
    "type": "tenant_role"
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://example.com/api/this_resource"
  }
}

List all available roles for a given tenant (Early Access)

get

List all available roles for a given tenant.

Required permissions

• View Tenant Roles (tenant.roles.read)

Authorizations

APITokenBearerAuth

AuthorizationstringRequired

API key value must be prefixed with "Token ".

Path parameters

tenant_idstring · uuidRequired

Unique identifier of the tenant.

Example: 00000000-0000-0000-0000-000000000000

Query parameters

versionstringRequired

Requested API version

Example: 2025-11-05Pattern: ^(wip|work-in-progress|experimental|beta|((([0-9]{4})-([0-1][0-9]))-((3[01])|(0[1-9])|([12][0-9]))(~(wip|work-in-progress|experimental|beta))?))$

namestringOptional

Role name filter.

Example: examplename

custombooleanOptional

Whether role is custom or not.

Example: false

assignable_by_mebooleanOptional

When true, only return roles that the current user can assign to others in the tenant.

Example: false

expand_permissionsbooleanOptional

option to show all permission types

Default: false

starting_afterstringOptional

Return the page of results immediately after this cursor

Example: v1.eyJpZCI6IjEwMDAifQo=

ending_beforestringOptional

Return the page of results immediately before this cursor

Example: v1.eyJpZCI6IjExMDAifQo=

limitinteger · int32 · min: 10 · max: 100Optional

Number of results to return per page

Default: 10Example: 10

Responses

200

Returns an array of roles that are the roles on a Tenant.

application/vnd.api+json

400

Bad Request: A parameter provided as a part of the request was invalid.

application/vnd.api+json

401

Unauthorized: the request requires an authentication token.

application/vnd.api+json

403

Forbidden: the request requires an authentication token with more or different permissions.

application/vnd.api+json

404

Not Found: The resource being operated on could not be found.

application/vnd.api+json

409

Conflict: The requested operation conflicts with the current state of the resource in some way.

application/vnd.api+json

500

Internal Server Error: An error was encountered while attempting to process the request.

application/vnd.api+json

get

/tenants/{tenant_id}/roles

HTTPcURLJavaScriptPython

GET /rest/tenants/{tenant_id}/roles?version=2025-11-05 HTTP/1.1
Host: api.snyk.io
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "attributes": {
        "custom": false,
        "description": "text",
        "name": "text",
        "normalized_name": "text",
        "permissions": [
          "text"
        ]
      },
      "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
      "meta": {
        "app_count": 1,
        "service_account_count": 1,
        "user_count": 1
      },
      "relationships": {
        "tenant": {
          "data": {
            "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
            "type": "tenant"
          }
        }
      },
      "type": "tenant_role"
    }
  ],
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "first": "https://example.com/api/resource?ending_before=v1.eyJpZCI6IjExIn0K",
    "last": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjMwIn0K",
    "next": "https://example.com/api/resource?starting_after=v1.eyJpZCI6IjEwIn0K"
  },
  "meta": {
    "permissions": [
      {
        "description": "Edit details of the Group",
        "name": "Edit Group Details",
        "parent": "group.read",
        "value": "text"
      }
    ]
  }
}

Update a specific tenant role by its id and its tenant id. (Early Access)

patch

Update attributes of a custom tenant role in a given tenant

Required permissions

• View Tenant Roles (tenant.roles.read)

• Edit Tenant Roles (tenant.roles.edit)

Authorizations

APITokenBearerAuth

AuthorizationstringRequired

API key value must be prefixed with "Token ".

Path parameters

tenant_idstring · uuidRequired

Unique identifier of the tenant.

Example: 00000000-0000-0000-0000-000000000000

role_idstring · uuidRequired

Unique identifier of the role.

Example: 00000000-0000-0000-0000-000000000000

Query parameters

versionstringRequired

Requested API version

Example: 2025-11-05Pattern: ^(wip|work-in-progress|experimental|beta|((([0-9]{4})-([0-1][0-9]))-((3[01])|(0[1-9])|([12][0-9]))(~(wip|work-in-progress|experimental|beta))?))$

forcebooleanOptional

flag to force the update of a role, required if users are assigned to the role

Example: false

Body

application/vnd.api+json

Responses

200

Returns the updated role.

application/vnd.api+json

400

Bad Request: A parameter provided as a part of the request was invalid.

application/vnd.api+json

401

Unauthorized: the request requires an authentication token.

application/vnd.api+json

403

Forbidden: the request requires an authentication token with more or different permissions.

application/vnd.api+json

404

Not Found: The resource being operated on could not be found.

application/vnd.api+json

409

Conflict: The requested operation conflicts with the current state of the resource in some way.

application/vnd.api+json

500

Internal Server Error: An error was encountered while attempting to process the request.

application/vnd.api+json

patch

/tenants/{tenant_id}/roles/{role_id}

HTTPcURLJavaScriptPython

PATCH /rest/tenants/{tenant_id}/roles/{role_id}?version=2025-11-05 HTTP/1.1
Host: api.snyk.io
Authorization: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 148

{
  "data": {
    "attributes": {
      "description": "text",
      "name": "text",
      "permissions": [
        "text"
      ]
    },
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "tenant_role"
  }
}

{
  "data": {
    "attributes": {
      "custom": false,
      "description": "text",
      "name": "text",
      "normalized_name": "text",
      "permissions": [
        "text"
      ]
    },
    "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
    "meta": {
      "app_count": 1,
      "service_account_count": 1,
      "user_count": 1
    },
    "relationships": {
      "tenant": {
        "data": {
          "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
          "type": "tenant"
        }
      }
    },
    "type": "tenant_role"
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://example.com/api/this_resource"
  }
}

Return a specific role by its id and its tenant id. (Early Access)

get

Return a role from a tenant by the tenant and role id with its details and permissions.

Required permissions

• View Tenant Roles (tenant.roles.read)

Authorizations

APITokenBearerAuth

AuthorizationstringRequired

API key value must be prefixed with "Token ".

Path parameters

tenant_idstring · uuidRequired

Unique identifier of the tenant.

Example: 00000000-0000-0000-0000-000000000000

role_idstring · uuidRequired

Unique identifier of the role.

Example: 00000000-0000-0000-0000-000000000000

Query parameters

versionstringRequired

Requested API version

Example: 2025-11-05Pattern: ^(wip|work-in-progress|experimental|beta|((([0-9]{4})-([0-1][0-9]))-((3[01])|(0[1-9])|([12][0-9]))(~(wip|work-in-progress|experimental|beta))?))$

has_users_assignedbooleanOptional

returns current memberships of the role in the meta relationships section

Default: false

Responses

200

Returns the requested role.

application/vnd.api+json

400

Bad Request: A parameter provided as a part of the request was invalid.

application/vnd.api+json

401

Unauthorized: the request requires an authentication token.

application/vnd.api+json

403

Forbidden: the request requires an authentication token with more or different permissions.

application/vnd.api+json

404

Not Found: The resource being operated on could not be found.

application/vnd.api+json

409

Conflict: The requested operation conflicts with the current state of the resource in some way.

application/vnd.api+json

500

Internal Server Error: An error was encountered while attempting to process the request.

application/vnd.api+json

get

/tenants/{tenant_id}/roles/{role_id}

HTTPcURLJavaScriptPython

GET /rest/tenants/{tenant_id}/roles/{role_id}?version=2025-11-05 HTTP/1.1
Host: api.snyk.io
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": {
    "attributes": {
      "custom": false,
      "description": "text",
      "name": "text",
      "normalized_name": "text",
      "permissions": [
        "text"
      ]
    },
    "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
    "meta": {
      "app_count": 1,
      "service_account_count": 1,
      "user_count": 1
    },
    "relationships": {
      "tenant": {
        "data": {
          "id": "d5b640e5-d88c-4c17-9bf0-93597b7a1ce2",
          "type": "tenant"
        }
      }
    },
    "type": "tenant_role"
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://example.com/api/this_resource"
  }
}

Delete a specific tenant role by its id and its tenant id. (Early Access)

delete

Delete a custom tenant role in a given tenant

Required permissions

• View Tenant Roles (tenant.roles.read)

• Delete Tenant Roles (tenant.roles.delete)

Authorizations

APITokenBearerAuth

AuthorizationstringRequired

API key value must be prefixed with "Token ".

Path parameters

tenant_idstring · uuidRequired

Unique identifier of the tenant.

Example: 00000000-0000-0000-0000-000000000000

role_idstring · uuidRequired

Unique identifier of the role.

Example: 00000000-0000-0000-0000-000000000000

Query parameters

versionstringRequired

Requested API version

Example: 2025-11-05Pattern: ^(wip|work-in-progress|experimental|beta|((([0-9]{4})-([0-1][0-9]))-((3[01])|(0[1-9])|([12][0-9]))(~(wip|work-in-progress|experimental|beta))?))$

Responses

204

Tenant role successfully deleted.

400

Bad Request: A parameter provided as a part of the request was invalid.

application/vnd.api+json

401

Unauthorized: the request requires an authentication token.

application/vnd.api+json

403

Forbidden: the request requires an authentication token with more or different permissions.

application/vnd.api+json

404

Not Found: The resource being operated on could not be found.

application/vnd.api+json

409

Conflict: The requested operation conflicts with the current state of the resource in some way.

application/vnd.api+json

500

Internal Server Error: An error was encountered while attempting to process the request.

application/vnd.api+json

delete

/tenants/{tenant_id}/roles/{role_id}

HTTPcURLJavaScriptPython

DELETE /rest/tenants/{tenant_id}/roles/{role_id}?version=2025-11-05 HTTP/1.1
Host: api.snyk.io
Authorization: YOUR_API_KEY
Accept: */*

No content