> For the complete documentation index, see [llms.txt](https://docs.soda.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soda.io/apis/rest-api/organisation.md).

# Organisation

Soda Cloud API Organisation-level Settings Endpoints

## List audit logs

> Returns persisted audit events for your organization, ordered by eventTime and then id, both ascending. Each event includes all of its audit steps.\
> \
> \- \`from\` and \`to\`: Required ISO8601 timestamps, normalized to UTC. Both bounds are inclusive. \`from\` must be before \`to\`, with at most 31 days between them. Example: \`2026-08-01T00:00:00+01:00\`.\
> \
> Filtering and ordering use the stored event timestamp at whole-second precision. Audit step timestamps retain their original precision.\
> \
> \- \`cursor\`: Omit for the first page. Pass the previous response's \`nextCursor\`, with the same other parameters, to continue after its last item. Cursors are opaque; invalid cursors return 400.\
> \
> \- \`size\`: Number of items per page, from 1 to 1000, default 100. The size may change between pages.\
> \
> The response contains \`content\` and, when more items are available, \`nextCursor\`. An absent \`nextCursor\` marks the end of the results. Page numbers and totals are not returned. Empty windows return 200 with an empty content array.\
> \
> The list is read from the analytical store, so an event can take a few seconds to appear after it is recorded. Pages reflect currently persisted data; there is no snapshot across requests. For incremental collection, use fixed windows ending in the past, replay overlapping windows to collect late-persisted events, and deduplicate by id. Reading this endpoint is itself audited.\
> \
> \## Authentication\
> \
> User authentication required: \`true\`\
> \
> This endpoint accepts authentication via API keys in the \`Basic\` authentication header, or a pre-authenticated token in HTTP cookie \`token\`. Cookie sessions extend automatically on each request.\
> \
> \## Authorization\
> \
> Users must have global role permission MANAGE\_ORGANISATION\_SETTINGS to execute this call.\
> \
> \## Auditable\
> \
> This API is marked as \*\*audited\*\* on execution.\
> \
> \## Tags\
> \
> \`Organisation\`\
> \
> \## Rate limiting\
> \
> 60 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Organisation-level Settings Endpoints","name":"Organisation"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiListAuditLogsResponse":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/AuditLogDTO"}},"nextCursor":{"type":"string"}},"required":["content"]},"AuditLogDTO":{"type":"object","properties":{"auditSteps":{"type":"array","description":"Details recorded during the operation, in recorded order. Empty when no steps were logged.","items":{"type":"object","$ref":"#/components/schemas/AuditLogStepDTO"}},"comment":{"type":"string","description":"Audited operation, usually a request or command name."},"email":{"type":"string"},"eventTime":{"type":"string","format":"date-time","description":"Timestamp of the overall operation in UTC at whole-second precision, used for filtering and ordering."},"id":{"type":"string"},"ipAddress":{"type":"string"},"maskedApiKey":{"type":"string","description":"Masked API key. Keys longer than eight characters retain the first and last two characters; keys of eight characters or fewer are fully masked."}},"required":["auditSteps","eventTime","id"]},"AuditLogStepDTO":{"type":"object","properties":{"comment":{"type":"string","description":"Detail or outcome recorded at this step of the operation."},"eventTime":{"type":"string","format":"date-time","description":"Timestamp of this step in UTC, retaining its original sub-second precision."}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/auditLogs":{"get":{"description":"Returns persisted audit events for your organization, ordered by eventTime and then id, both ascending. Each event includes all of its audit steps.\n\n- `from` and `to`: Required ISO8601 timestamps, normalized to UTC. Both bounds are inclusive. `from` must be before `to`, with at most 31 days between them. Example: `2026-08-01T00:00:00+01:00`.\n\nFiltering and ordering use the stored event timestamp at whole-second precision. Audit step timestamps retain their original precision.\n\n- `cursor`: Omit for the first page. Pass the previous response's `nextCursor`, with the same other parameters, to continue after its last item. Cursors are opaque; invalid cursors return 400.\n\n- `size`: Number of items per page, from 1 to 1000, default 100. The size may change between pages.\n\nThe response contains `content` and, when more items are available, `nextCursor`. An absent `nextCursor` marks the end of the results. Page numbers and totals are not returned. Empty windows return 200 with an empty content array.\n\nThe list is read from the analytical store, so an event can take a few seconds to appear after it is recorded. Pages reflect currently persisted data; there is no snapshot across requests. For incremental collection, use fixed windows ending in the past, replay overlapping windows to collect late-persisted events, and deduplicate by id. Reading this endpoint is itself audited.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis endpoint accepts authentication via API keys in the `Basic` authentication header, or a pre-authenticated token in HTTP cookie `token`. Cookie sessions extend automatically on each request.\n\n## Authorization\n\nUsers must have global role permission MANAGE_ORGANISATION_SETTINGS to execute this call.\n\n## Auditable\n\nThis API is marked as **audited** on execution.\n\n## Tags\n\n`Organisation`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"GET/api/v1/auditLogs","parameters":[{"in":"query","name":"cursor","schema":{"type":"string"}},{"in":"query","name":"from","required":true,"schema":{"type":"string","format":"date-time"}},{"in":"query","name":"size","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"to","required":true,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiListAuditLogsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"List audit logs","tags":["Organisation"]}}}}
```

## List global responsibilities

> This endpoint returns which users and user groups hold which global role in your organization's Soda Cloud account, including the assignments of the built-in Admin role.\
> \
> Legacy service users are left out; their global role cannot be changed through this API.\
> \
> This GET is a paginated API that uses the following parameters to request specific details:\
> \
> \- \`size\`: Supply an integer value between 1 and 100, inclusive. The default value is 100.\
> \
> \- \`page\`: Supply an integer value. The default value is 0.\
> \
> \## Authentication\
> \
> User authentication required: \`true\`\
> \
> This endpoint accepts authentication via API keys in the \`Basic\` authentication header, or a pre-authenticated token in HTTP cookie \`token\`. Cookie sessions extend automatically on each request.\
> \
> \## Authorization\
> \
> Users must have global role permission MANAGE\_ORGANISATION\_SETTINGS to execute this call.\
> \
> \## Tags\
> \
> \`Organisation\`\
> \
> \## Rate limiting\
> \
> 60 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Organisation-level Settings Endpoints","name":"Organisation"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiGlobalResponsibilitiesResponse":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/GlobalResponsibilityContentDTO"}},"first":{"type":"boolean"},"last":{"type":"boolean"},"number":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int32"},"totalPages":{"type":"integer","format":"int32"}},"required":["content","first","last","number","size","totalElements","totalPages"]},"GlobalResponsibilityContentDTO":{"type":"object","properties":{"managed":{"type":"boolean","description":"True when Soda maintains this assignment itself, for example one granted through an identity provider group. Updating the global responsibilities leaves managed assignments untouched."},"role":{"type":"object","$ref":"#/components/schemas/GlobalRoleContentDTO"},"type":{"type":"object","$ref":"#/components/schemas/ResponsibilityTypeDTO"},"userGroupId":{"type":"string"},"userId":{"type":"string"}},"required":["managed","role","type"]},"GlobalRoleContentDTO":{"type":"object","properties":{"admin":{"type":"boolean","description":"True for the built-in Admin role. It grants every right in the organization, reports every permission below as true, and can be neither updated nor deleted."},"createAgreements":{"type":"boolean"},"createApiKeys":{"type":"boolean"},"createNewDatasourcesAndDatasets":{"type":"boolean"},"description":{"type":"string"},"id":{"type":"string"},"manageAttributes":{"type":"boolean"},"manageDataProducts":{"type":"boolean"},"manageDataStandards":{"type":"boolean"},"manageDatasourcesAndRunners":{"type":"boolean"},"manageNotificationRules":{"type":"boolean"},"manageOrganisationSettings":{"type":"boolean"},"manageScanDefinitions":{"type":"boolean"},"name":{"type":"string"}},"required":["id","name"]},"ResponsibilityTypeDTO":{"type":"string","enum":["user","userGroup"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/organisation/responsibilities":{"get":{"description":"This endpoint returns which users and user groups hold which global role in your organization's Soda Cloud account, including the assignments of the built-in Admin role.\n\nLegacy service users are left out; their global role cannot be changed through this API.\n\nThis GET is a paginated API that uses the following parameters to request specific details:\n\n- `size`: Supply an integer value between 1 and 100, inclusive. The default value is 100.\n\n- `page`: Supply an integer value. The default value is 0.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis endpoint accepts authentication via API keys in the `Basic` authentication header, or a pre-authenticated token in HTTP cookie `token`. Cookie sessions extend automatically on each request.\n\n## Authorization\n\nUsers must have global role permission MANAGE_ORGANISATION_SETTINGS to execute this call.\n\n## Tags\n\n`Organisation`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"GET/api/v1/organisation/responsibilities","parameters":[{"in":"query","name":"page","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"size","schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiGlobalResponsibilitiesResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"List global responsibilities","tags":["Organisation"]}}}}
```

## Update global responsibilities

> This endpoint sets which users and user groups hold which global role in your organization's Soda Cloud account.\
> \
> \*\*Note\*\*: This API fully replaces the existing global responsibilities. The entire list must be provided in the request, including both new and existing entries, as any omission results in its removal. Managed assignments and the global roles of legacy service users are kept as they are.\
> \
> At least one Admin assignment must remain. Only Soda Cloud Admins can grant or revoke the Admin role; for other callers the request answers 403 when it changes an Admin assignment.\
> \
> When successful, the response is \`201\` with a \`Location\` header pointing to the global responsibilities.\
> \
> \## Authentication\
> \
> User authentication required: \`true\`\
> \
> This endpoint accepts authentication via API keys in the \`Basic\` authentication header, or a pre-authenticated token in HTTP cookie \`token\`. Cookie sessions extend automatically on each request.\
> \
> \## Authorization\
> \
> Users must have global role permission MANAGE\_ORGANISATION\_SETTINGS to execute this call.\
> \
> \## Auditable\
> \
> This API is marked as \*\*audited\*\* on execution.\
> \
> \## Tags\
> \
> \`Organisation\`\
> \
> \## Rate limiting\
> \
> 60 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Organisation-level Settings Endpoints","name":"Organisation"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiUpdateGlobalResponsibilitiesRequestDTO":{"type":"object","properties":{"responsibilities":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/GlobalResponsibilityContentRequestDTO"}}},"required":["responsibilities"]},"GlobalResponsibilityContentRequestDTO":{"type":"object","properties":{"roleId":{"type":"string"},"type":{"type":"object","$ref":"#/components/schemas/ResponsibilityTypeDTO"},"userGroupId":{"type":"string"},"userId":{"type":"string"}},"required":["roleId","type"]},"ResponsibilityTypeDTO":{"type":"string","enum":["user","userGroup"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/organisation/responsibilities":{"post":{"description":"This endpoint sets which users and user groups hold which global role in your organization's Soda Cloud account.\n\n**Note**: This API fully replaces the existing global responsibilities. The entire list must be provided in the request, including both new and existing entries, as any omission results in its removal. Managed assignments and the global roles of legacy service users are kept as they are.\n\nAt least one Admin assignment must remain. Only Soda Cloud Admins can grant or revoke the Admin role; for other callers the request answers 403 when it changes an Admin assignment.\n\nWhen successful, the response is `201` with a `Location` header pointing to the global responsibilities.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis endpoint accepts authentication via API keys in the `Basic` authentication header, or a pre-authenticated token in HTTP cookie `token`. Cookie sessions extend automatically on each request.\n\n## Authorization\n\nUsers must have global role permission MANAGE_ORGANISATION_SETTINGS to execute this call.\n\n## Auditable\n\nThis API is marked as **audited** on execution.\n\n## Tags\n\n`Organisation`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"POST/api/v1/organisation/responsibilities","requestBody":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiUpdateGlobalResponsibilitiesRequestDTO"}}},"required":true},"responses":{"201":{"description":"Created","headers":{"Location":{"schema":{"type":"string"}}}},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Update global responsibilities","tags":["Organisation"]}}}}
```

## List global roles

> This endpoint returns the global roles of your organization's Soda Cloud account. Global roles grant organization-wide permissions, such as managing data sources and runners or managing organization settings.\
> \
> The list includes the built-in Admin role, marked with \`admin: true\`, so that its id can be used in global responsibilities.\
> \
> This GET is a paginated API that uses the following parameters to request specific details:\
> \
> \- \`size\`: Supply an integer value between 1 and 100, inclusive. The default value is 100.\
> \
> \- \`page\`: Supply an integer value. The default value is 0.\
> \
> \## Authentication\
> \
> User authentication required: \`true\`\
> \
> This endpoint accepts authentication via API keys in the \`Basic\` authentication header, or a pre-authenticated token in HTTP cookie \`token\`. Cookie sessions extend automatically on each request.\
> \
> \## Authorization\
> \
> Any Soda Cloud user in your organization may execute this query.\
> \
> \## Tags\
> \
> \`Organisation\`\
> \
> \## Rate limiting\
> \
> 60 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Organisation-level Settings Endpoints","name":"Organisation"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiGlobalRolesResponse":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/GlobalRoleContentDTO"}},"first":{"type":"boolean"},"last":{"type":"boolean"},"number":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int32"},"totalPages":{"type":"integer","format":"int32"}},"required":["content","first","last","number","size","totalElements","totalPages"]},"GlobalRoleContentDTO":{"type":"object","properties":{"admin":{"type":"boolean","description":"True for the built-in Admin role. It grants every right in the organization, reports every permission below as true, and can be neither updated nor deleted."},"createAgreements":{"type":"boolean"},"createApiKeys":{"type":"boolean"},"createNewDatasourcesAndDatasets":{"type":"boolean"},"description":{"type":"string"},"id":{"type":"string"},"manageAttributes":{"type":"boolean"},"manageDataProducts":{"type":"boolean"},"manageDataStandards":{"type":"boolean"},"manageDatasourcesAndRunners":{"type":"boolean"},"manageNotificationRules":{"type":"boolean"},"manageOrganisationSettings":{"type":"boolean"},"manageScanDefinitions":{"type":"boolean"},"name":{"type":"string"}},"required":["id","name"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/organisation/roles":{"get":{"description":"This endpoint returns the global roles of your organization's Soda Cloud account. Global roles grant organization-wide permissions, such as managing data sources and runners or managing organization settings.\n\nThe list includes the built-in Admin role, marked with `admin: true`, so that its id can be used in global responsibilities.\n\nThis GET is a paginated API that uses the following parameters to request specific details:\n\n- `size`: Supply an integer value between 1 and 100, inclusive. The default value is 100.\n\n- `page`: Supply an integer value. The default value is 0.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis endpoint accepts authentication via API keys in the `Basic` authentication header, or a pre-authenticated token in HTTP cookie `token`. Cookie sessions extend automatically on each request.\n\n## Authorization\n\nAny Soda Cloud user in your organization may execute this query.\n\n## Tags\n\n`Organisation`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"GET/api/v1/organisation/roles","parameters":[{"in":"query","name":"page","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"size","schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiGlobalRolesResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"List global roles","tags":["Organisation"]}}}}
```

## Create a global role

> This endpoint creates a custom global role in your organization's Soda Cloud account. Global roles define a named set of organization-wide permissions, such as managing data sources and runners, managing attributes or managing organization settings.\
> \
> Global role names are unique within the organization, regardless of case. The name of the built-in Admin role is taken as well; dataset and datasource roles may share a name with a global role.\
> \
> Once created, the role can be assigned to users or user groups through the global responsibilities endpoint.\
> \
> \## Authentication\
> \
> User authentication required: \`true\`\
> \
> This endpoint accepts authentication via API keys in the \`Basic\` authentication header, or a pre-authenticated token in HTTP cookie \`token\`. Cookie sessions extend automatically on each request.\
> \
> \## Authorization\
> \
> Users must have global role permission MANAGE\_ORGANISATION\_SETTINGS to execute this call.\
> \
> \## Auditable\
> \
> This API is marked as \*\*audited\*\* on execution.\
> \
> \## Tags\
> \
> \`Organisation\`\
> \
> \## Rate limiting\
> \
> 60 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Organisation-level Settings Endpoints","name":"Organisation"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiGlobalRoleRequestDTO":{"type":"object","properties":{"createAgreements":{"type":"boolean"},"createApiKeys":{"type":"boolean"},"createNewDatasourcesAndDatasets":{"type":"boolean"},"description":{"type":"string"},"manageAttributes":{"type":"boolean"},"manageDataProducts":{"type":"boolean"},"manageDataStandards":{"type":"boolean"},"manageDatasourcesAndRunners":{"type":"boolean"},"manageNotificationRules":{"type":"boolean"},"manageOrganisationSettings":{"type":"boolean"},"manageScanDefinitions":{"type":"boolean"},"name":{"type":"string"}},"required":["name"]},"PublicApiCreateGlobalRoleResponse":{"type":"object","properties":{"globalRole":{"type":"object","$ref":"#/components/schemas/GlobalRoleContentDTO"}},"required":["globalRole"]},"GlobalRoleContentDTO":{"type":"object","properties":{"admin":{"type":"boolean","description":"True for the built-in Admin role. It grants every right in the organization, reports every permission below as true, and can be neither updated nor deleted."},"createAgreements":{"type":"boolean"},"createApiKeys":{"type":"boolean"},"createNewDatasourcesAndDatasets":{"type":"boolean"},"description":{"type":"string"},"id":{"type":"string"},"manageAttributes":{"type":"boolean"},"manageDataProducts":{"type":"boolean"},"manageDataStandards":{"type":"boolean"},"manageDatasourcesAndRunners":{"type":"boolean"},"manageNotificationRules":{"type":"boolean"},"manageOrganisationSettings":{"type":"boolean"},"manageScanDefinitions":{"type":"boolean"},"name":{"type":"string"}},"required":["id","name"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/organisation/roles":{"post":{"description":"This endpoint creates a custom global role in your organization's Soda Cloud account. Global roles define a named set of organization-wide permissions, such as managing data sources and runners, managing attributes or managing organization settings.\n\nGlobal role names are unique within the organization, regardless of case. The name of the built-in Admin role is taken as well; dataset and datasource roles may share a name with a global role.\n\nOnce created, the role can be assigned to users or user groups through the global responsibilities endpoint.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis endpoint accepts authentication via API keys in the `Basic` authentication header, or a pre-authenticated token in HTTP cookie `token`. Cookie sessions extend automatically on each request.\n\n## Authorization\n\nUsers must have global role permission MANAGE_ORGANISATION_SETTINGS to execute this call.\n\n## Auditable\n\nThis API is marked as **audited** on execution.\n\n## Tags\n\n`Organisation`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"POST/api/v1/organisation/roles","requestBody":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiGlobalRoleRequestDTO"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiCreateGlobalRoleResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Create a global role","tags":["Organisation"]}}}}
```

## Update a global role

> This endpoint updates the name, description and permissions of a global role, including the built-in User and Service Account roles. The request replaces every permission of the role, so send the ones to keep. The description is replaced too: omitting it clears it.\
> \
> The built-in Admin role cannot be updated; the endpoint answers 400 for it.\
> \
> Changes apply immediately to every user and user group assigned this role.\
> \
> \## Authentication\
> \
> User authentication required: \`true\`\
> \
> This endpoint accepts authentication via API keys in the \`Basic\` authentication header, or a pre-authenticated token in HTTP cookie \`token\`. Cookie sessions extend automatically on each request.\
> \
> \## Authorization\
> \
> Users must have global role permission MANAGE\_ORGANISATION\_SETTINGS to execute this call.\
> \
> \## Auditable\
> \
> This API is marked as \*\*audited\*\* on execution.\
> \
> \## Tags\
> \
> \`Organisation\`\
> \
> \## Rate limiting\
> \
> 60 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Organisation-level Settings Endpoints","name":"Organisation"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiGlobalRoleRequestDTO":{"type":"object","properties":{"createAgreements":{"type":"boolean"},"createApiKeys":{"type":"boolean"},"createNewDatasourcesAndDatasets":{"type":"boolean"},"description":{"type":"string"},"manageAttributes":{"type":"boolean"},"manageDataProducts":{"type":"boolean"},"manageDataStandards":{"type":"boolean"},"manageDatasourcesAndRunners":{"type":"boolean"},"manageNotificationRules":{"type":"boolean"},"manageOrganisationSettings":{"type":"boolean"},"manageScanDefinitions":{"type":"boolean"},"name":{"type":"string"}},"required":["name"]},"PublicApiUpdateGlobalRoleResponse":{"type":"object","properties":{"globalRole":{"type":"object","$ref":"#/components/schemas/GlobalRoleContentDTO"}},"required":["globalRole"]},"GlobalRoleContentDTO":{"type":"object","properties":{"admin":{"type":"boolean","description":"True for the built-in Admin role. It grants every right in the organization, reports every permission below as true, and can be neither updated nor deleted."},"createAgreements":{"type":"boolean"},"createApiKeys":{"type":"boolean"},"createNewDatasourcesAndDatasets":{"type":"boolean"},"description":{"type":"string"},"id":{"type":"string"},"manageAttributes":{"type":"boolean"},"manageDataProducts":{"type":"boolean"},"manageDataStandards":{"type":"boolean"},"manageDatasourcesAndRunners":{"type":"boolean"},"manageNotificationRules":{"type":"boolean"},"manageOrganisationSettings":{"type":"boolean"},"manageScanDefinitions":{"type":"boolean"},"name":{"type":"string"}},"required":["id","name"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/organisation/roles/{roleId}":{"post":{"description":"This endpoint updates the name, description and permissions of a global role, including the built-in User and Service Account roles. The request replaces every permission of the role, so send the ones to keep. The description is replaced too: omitting it clears it.\n\nThe built-in Admin role cannot be updated; the endpoint answers 400 for it.\n\nChanges apply immediately to every user and user group assigned this role.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis endpoint accepts authentication via API keys in the `Basic` authentication header, or a pre-authenticated token in HTTP cookie `token`. Cookie sessions extend automatically on each request.\n\n## Authorization\n\nUsers must have global role permission MANAGE_ORGANISATION_SETTINGS to execute this call.\n\n## Auditable\n\nThis API is marked as **audited** on execution.\n\n## Tags\n\n`Organisation`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"POST/api/v1/organisation/roles/{roleId}","parameters":[{"in":"path","name":"roleId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiGlobalRoleRequestDTO"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiUpdateGlobalRoleResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Update a global role","tags":["Organisation"]}}}}
```

## Delete a global role

> This endpoint deletes a global role from your organization's Soda Cloud account.\
> \
> Deletion is performed asynchronously and may take some time to complete.\
> \
> Deletion fails with 400 while the role is still assigned to a user or user group, while it is used in the responsibility settings of the organization (the default dataset owner or data source owner role, or a default dataset or data source assignment), or while it is the role of new service accounts. The built-in Admin role cannot be deleted.\
> \
> \## Authentication\
> \
> User authentication required: \`true\`\
> \
> This endpoint accepts authentication via API keys in the \`Basic\` authentication header, or a pre-authenticated token in HTTP cookie \`token\`. Cookie sessions extend automatically on each request.\
> \
> \## Authorization\
> \
> Users must have global role permission MANAGE\_ORGANISATION\_SETTINGS to execute this call.\
> \
> \## Auditable\
> \
> This API is marked as \*\*audited\*\* on execution.\
> \
> \## Tags\
> \
> \`Organisation\`\
> \
> \## Rate limiting\
> \
> 60 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Organisation-level Settings Endpoints","name":"Organisation"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiDeleteGlobalRoleResponse":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/organisation/roles/{roleId}":{"delete":{"description":"This endpoint deletes a global role from your organization's Soda Cloud account.\n\nDeletion is performed asynchronously and may take some time to complete.\n\nDeletion fails with 400 while the role is still assigned to a user or user group, while it is used in the responsibility settings of the organization (the default dataset owner or data source owner role, or a default dataset or data source assignment), or while it is the role of new service accounts. The built-in Admin role cannot be deleted.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis endpoint accepts authentication via API keys in the `Basic` authentication header, or a pre-authenticated token in HTTP cookie `token`. Cookie sessions extend automatically on each request.\n\n## Authorization\n\nUsers must have global role permission MANAGE_ORGANISATION_SETTINGS to execute this call.\n\n## Auditable\n\nThis API is marked as **audited** on execution.\n\n## Tags\n\n`Organisation`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"DELETE/api/v1/organisation/roles/{roleId}","parameters":[{"in":"path","name":"roleId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiDeleteGlobalRoleResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Delete a global role","tags":["Organisation"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.soda.io/apis/rest-api/organisation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.