openapi: 3.0.1 info: title: SlashID Groups Organizations API description: "This is the [OpenAPI](https://www.openapis.org/) specification for communicating with the [SlashID](https://www.slashid.dev/) service.\n\nThe latest version of the OpenAPI API spec can be fetched from [our CDN](https://cdn.slashid.com/slashid-openapi-latest.yaml).\n\nWe recommend you use an [OpenAPI SDK generator](https://openapi.tools/#sdk) to create a client library in your programming language,\nbut you can also use this documentation to make HTTP calls directly.\n\n> **Compatibility note**: We aim to keep wire compatibility whenever we update the API, but parts of the specification may occasionally be refactored.\n If you use an SDK generator, your code may require minor changes between versions.\n" version: '1.1' termsOfService: https://www.slashid.dev/terms-of-use/ contact: name: API Support email: contact@slashid.dev servers: - url: https://api.slashid.com description: Production - url: https://api.sandbox.slashid.com description: Sandbox security: - ApiKeyAuth: [] tags: - name: Organizations paths: /persons/{person_id}: parameters: - $ref: '#/components/parameters/PersonIDPathParam' - $ref: '#/components/parameters/OrgIDHeader' delete: operationId: DeletePersonsPersonId x-rbac-enabled: true x-rbac-allowed-groups: admin x-manager-rbac-allowed-groups: admin tags: - Organizations summary: Delete a person from an organization description: 'Remove the person, specified by its ID, from the organization. Note that access to all the attributes associated with this person will be permanently revoked.' responses: '204': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' /persons/{person_id}/organizations: parameters: - $ref: '#/components/parameters/PersonIDPathParam' - $ref: '#/components/parameters/OrgIDHeader' get: operationId: GetPersonsPersonIdOrganizations x-rbac-enabled: true x-rbac-allowed-groups: admin,member tags: - Organizations summary: Retrieve the list of person's organizations description: "Retrieve details of all the organizations a person belongs to, including:\n - The organization of the request: the person must be a member of the organization you authenticate\n with for you to be allowed to retrieve this list\n - Any sub- and super-organizations that share the person pool with the organization of the request:\n A hierarchy of organizations can be created using [this API endpoint](/docs/api/post-organizations-suborganizations).\n When organizations are configured to share a person pool, if the same person registers with multiple organizations\n in the pool using the same handle, all organizations will see the same person ID for that person.\n" parameters: - $ref: '#/components/parameters/GetPersonsPersonIdOrganizationsFilterQueryParam' responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponseBase' - type: object properties: result: $ref: '#/components/schemas/GetPersonOrganizationsResponse' required: - result '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /organizations: parameters: - $ref: '#/components/parameters/OrgIDHeader' get: operationId: GetOrganizations x-rbac-enabled: true x-rbac-allowed-groups: admin,member tags: - Organizations summary: Retrieve information about an organization description: 'Retrieve information about which other organizations the given shares persons and groups with. ' responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponseBase' - type: object properties: result: $ref: '#/components/schemas/OrganizationResponse' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' delete: operationId: DeleteOrganizations x-rbac-enabled: false tags: - Organizations summary: Delete an organization description: 'Delete a non-root, leaf organization, including all its persons memberships and their groups memberships and attributes. ' parameters: - $ref: '#/components/parameters/RequiredConsistencyHeader' - $ref: '#/components/parameters/RequiredConsistencyTimeoutHeader' - $ref: '#/components/parameters/DeleteSuborganizationOptionalQueryParam' - $ref: '#/components/parameters/ConfirmationTimestampQueryParam' responses: '204': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' /organizations/suborganizations: parameters: - $ref: '#/components/parameters/OrgIDHeader' get: operationId: GetOrganizationsSuborganizations x-rbac-enabled: true x-rbac-allowed-groups: admin,member tags: - Organizations summary: List suborganizations description: 'Retrieve a list of all descendant organizations. ' parameters: - $ref: '#/components/parameters/OrganizationsFilterQueryParam' responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponseBase' - type: object properties: result: type: array items: $ref: '#/components/schemas/OrganizationID' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' post: operationId: PostOrganizationsSuborganizations x-rbac-enabled: true x-rbac-allowed-groups: admin tags: - Organizations summary: Create a suborganization description: 'Create a new organization subordinate to your organization. ' parameters: - $ref: '#/components/parameters/RequiredConsistencyHeader' - $ref: '#/components/parameters/RequiredConsistencyTimeoutHeader' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/SuborganizationCreateRequest' responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponseBase' - type: object properties: result: $ref: '#/components/schemas/OrganizationCreateResponse' '402': $ref: '#/components/responses/PaymentRequired' '412': $ref: '#/components/responses/PreconditionFailed' /organizations/api-keys: parameters: - $ref: '#/components/parameters/OrgIDHeader' - $ref: '#/components/parameters/RequiredConsistencyHeader' - $ref: '#/components/parameters/RequiredConsistencyTimeoutHeader' put: operationId: PutOrganizationsApiKeys x-rbac-enabled: true x-rbac-allowed-groups: admin tags: - Organizations summary: Generate a new API key for the specified organization description: A new API key is created and returned. The previous API key will no longer be valid after this. responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponseBase' - type: object properties: result: $ref: '#/components/schemas/OrganizationsPutAPIKeyResponse' '400': $ref: '#/components/responses/BadRequest' /organizations/config: parameters: - $ref: '#/components/parameters/OrgIDHeader' get: operationId: GetOrganizationsConfig x-rbac-enabled: true x-rbac-allowed-groups: admin,member,impersonator,saml-admin,uar-certifier,uar-campaign-manager,cs-id-verifier tags: - Organizations summary: Get organization config description: Get the current configuration for your organization responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponseBase' - type: object properties: result: $ref: '#/components/schemas/OrganizationConfig' required: - result '400': $ref: '#/components/responses/BadRequest' patch: operationId: PatchOrganizationsConfig x-rbac-enabled: true x-rbac-allowed-groups: admin tags: - Organizations summary: Update organization config description: 'Modify the configuration for your organization. The token duration determines the number of seconds a token issued by SlashID will be valid for. If not set, or set to 0, the default duration of 24 hours will be used for all tokens. The groups claim name determines the name of the claim in the token payload where a user''s groups are found. If not set, or set to the empty string, the default claim name `groups` will be used for all tokens. ' parameters: - $ref: '#/components/parameters/RequiredConsistencyHeader' - $ref: '#/components/parameters/RequiredConsistencyTimeoutHeader' requestBody: content: application/json: schema: $ref: '#/components/schemas/OrganizationConfigPatchRequest' responses: '204': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' /organizations/quota/current-tier: parameters: - $ref: '#/components/parameters/OrgIDHeader' get: operationId: GetOrganizationsQuotaCurrentTier x-rbac-enabled: true x-rbac-allowed-groups: admin,member tags: - Organizations summary: Get current pricing tier details. description: This returns the quotas associated with your organization's current pricing tier. responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponseBase' - type: object properties: result: $ref: '#/components/schemas/PricingTierConstraints' required: - result '400': $ref: '#/components/responses/BadRequest' /organizations/quota/all-tiers: get: operationId: GetOrganizationsQuotaAllTiers tags: - Organizations summary: Get details on all pricing tiers. description: This returns the quotas for each available pricing tier. responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponseBase' - type: object properties: result: type: array items: $ref: '#/components/schemas/PricingTierConstraints' required: - result '400': $ref: '#/components/responses/BadRequest' /organizations/quota/usage: parameters: - $ref: '#/components/parameters/OrgIDHeader' get: operationId: GetOrganizationsQuotaUsage x-rbac-enabled: true x-rbac-allowed-groups: admin,member tags: - Organizations summary: Get resource usage for the organization hierarchy. description: This returns the resources used by your organization and its suborganizations. This can be used to evaluate the need for a tier upgrade. responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponseBase' - type: object properties: result: $ref: '#/components/schemas/OrganizationUsageDetails' required: - result '400': $ref: '#/components/responses/BadRequest' /organizations/attribute-buckets: parameters: - $ref: '#/components/parameters/OrgIDHeader' get: operationId: GetOrganizationsAttributeBuckets x-rbac-enabled: true x-rbac-allowed-groups: admin,member tags: - Organizations summary: List organization's attribute buckets description: Get a list of available attribute buckets for your organization responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/APIResponseBase' - type: object properties: result: type: array items: $ref: '#/components/schemas/AttributeBucket' required: - result '400': $ref: '#/components/responses/BadRequest' components: parameters: RequiredConsistencyHeader: name: SlashID-Required-Consistency in: header description: 'The consistency level required for this request. If the consistency level is not achieved within the timeout, the request will fail with a 408 Request Timeout error. 408 Request Timeout error indicates that request was not handled within the timeout, but it may still be handled after request timeout. Allowed values: * `local_region`: Wait while the request executes in the local region. * `all_regions`: Wait while the request executes across all regions. You can learn more about our replication model on our [Cross-region Replication Model](/docs/access/concepts/replication) page. ' schema: type: string enum: - local_region - all_regions default: local_region OrgIDHeader: name: SlashID-OrgID in: header schema: type: string required: true description: The organization ID example: af5fbd30-7ce7-4548-8b30-4cd59cb2aba1 GetPersonsPersonIdOrganizationsFilterQueryParam: in: query name: filter schema: type: string description: A filter to be applied to the result list, using the [SCIM 2.0 Filter syntax](https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.2). examples: permission_write: summary: Returns only persons with 'write' permission. value: permission eq "write" ConfirmationTimestampQueryParam: in: query name: confirmation_timestamp schema: type: string description: RFC3339 timestamp. Must be between -60s and -10s from the current time to be accepted by the endpoint. format: date-time required: false RequiredConsistencyTimeoutHeader: name: SlashID-Required-Consistency-Timeout in: header description: 'The maximum amount of seconds to wait for the requested consistency level to be achieved. If the consistency level is not achieved within this time, the request will fail with a 408 Request Timeout error. 408 Request Timeout error indicates that request was not handled within the timeout, but it may still be handled after request timeout. You can learn more about our replication model on our [Cross-region Replication Model](/docs/access/concepts/replication) page. ' schema: type: integer default: 30 maximum: 120 minimum: 1 OrganizationsFilterQueryParam: in: query name: filter schema: type: string description: A filter to be applied to the result list, using the [SCIM 2.0 Filter syntax](https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.2). examples: org_name_eq: summary: Returns only organizations named exactly "my_org" value: name eq "my_org" org_name_co: summary: Returns only organizations with the string "some_str" in the name value: name co "some_str" org_name_sw: summary: Returns only organizations with name starting in "my_prefix" value: name sw "my_prefix" org_id_eq: summary: Returns only the organization with the specified ID, if it exists value: id eq "0be15c7a-a72d-47c4-ab9a-9a88bac3416d" parent_org_id_eq: summary: Returns only organizations children of the org with the specified ID value: parent_org_id eq "0be15c7a-a72d-47c4-ab9a-9a88bac3416d" DeleteSuborganizationOptionalQueryParam: in: query name: delete_suborganizations schema: type: boolean description: Whether to delete suborganizations of the organization being deleted. If this option is provided a valid `confirmation_timestamp` param is also required for the operation to proceed. required: false PersonIDPathParam: name: person_id description: The person ID example: 903c1ff9-f2cc-435c-b242-9d8a690fcf0a in: path required: true schema: type: string responses: Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/APIResponseBase' NoContent: description: No content PreconditionFailed: description: Precondition Failed content: application/json: schema: $ref: '#/components/schemas/APIResponseBase' NotFound: description: Not Found content: application/json: schema: $ref: '#/components/schemas/APIResponseBase' Conflict: description: Conflict content: application/json: schema: $ref: '#/components/schemas/APIResponseBase' PaymentRequired: description: Pricing Tier Violation - operation violated the limits specified in its pricing tier. content: application/json: schema: $ref: '#/components/schemas/APIResponseBase' BadRequest: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/APIResponseBase' schemas: Bytes: type: string PricingTierConstraints: type: object description: 'Details of the constraints applied to a specific pricing tier. ' required: - name - custom_templates_allowed - nhi_external_connections_allowed properties: name: $ref: '#/components/schemas/PricingTier' custom_templates_allowed: description: Indicates if custom email and SMS message templates are allowed type: boolean nhi_external_connections_allowed: description: Indicates if external connections to non-human identity sources are allowed type: boolean max_suborganizations: description: Indicates the maximum number of the suborganizations in the hierarchy, not including the root organization. `null` indicates no limit. type: integer format: int64 max_persons: description: Indicates the maximum number of persons allowed, including all suborganizations in the hierarchy. `null` indicates no limit. type: integer format: int64 max_groups: description: Indicates the maximum number of groups allowed, including all suborganizations in the hierarchy. `null` indicates no limit. type: integer format: int64 OrganizationResponse: allOf: - $ref: '#/components/schemas/Organization' - type: object required: - persons_pool_org_ids - group_pool_org_ids properties: parent_id: description: The ID of the parent organization. $ref: '#/components/schemas/OrganizationID' persons_pool_org_ids: description: The list of organizations or suborganizations that share user identities with this organization type: array items: $ref: '#/components/schemas/OrganizationID' group_pool_org_ids: description: The list of organizations or suborganizations that share user groups with this organization type: array items: $ref: '#/components/schemas/OrganizationID' inherits_rbac_pools: type: boolean PersonHandle: required: - type - value type: object properties: type: $ref: '#/components/schemas/PersonHandleType' value: type: string example: user@user.com GetPersonOrganizationsResponse: type: array items: $ref: '#/components/schemas/OrganizationDetails' OrganizationDetails: allOf: - $ref: '#/components/schemas/Organization' - type: object properties: managed_organizations: type: array items: $ref: '#/components/schemas/Organization' AttributePermissions: type: string description: The access level for end-users to attributes in this bucket. enum: - no_access - read_only - read_write PricingTier: type: string description: 'The tier associated with a root organization. Your organization may be subject to various constraints depending on its tier, such as maximum number of users, rate-limits, etc. ' enum: - free-trial - professional - enterprise - enterprise-with-nhi - identity-protection OrganizationUsageDetails: type: object description: 'Details of how many suborganization/persons/groups have been used by this organization hierarchy. ' required: - num_suborganizations - num_persons - num_groups properties: pricing_tier_details: $ref: '#/components/schemas/PricingTierConstraints' num_suborganizations: description: Indicates the number of the suborganizations in the hierarchy, not including the root organization. type: integer format: int64 num_persons: description: Indicates the number of persons, including all suborganizations in the hierarchy. type: integer format: int64 num_groups: description: Indicates the groups, including all suborganizations in the hierarchy. type: integer format: int64 FactorMethod: type: string description: Allowed login factor enum: - webauthn - email_link - sms_link - otp_via_sms - otp_via_email - totp - oidc - saml - api - direct_id - password - impersonate - anonymous AttributeSharingScope: type: string description: The scope in which attributes in this bucket are available enum: - organization - person_pool APIResponseBase: type: object properties: meta: $ref: '#/components/schemas/APIMeta' errors: type: array items: $ref: '#/components/schemas/APIResponseError' APIPagination: type: object required: - limit - offset - total_count properties: limit: type: integer offset: type: integer total_count: type: integer format: int64 GlobPattern: type: string description: A glob pattern example: '*@example.com' PersonHandleType: type: string enum: - email_address - phone_number - username example: email_address APICursorPagination: type: object required: - limit - cursor - total_count properties: limit: type: integer cursor: type: string total_count: type: integer format: int64 OrganizationCreateResponse: allOf: - $ref: '#/components/schemas/Organization' - type: object required: - api_key properties: api_key: $ref: '#/components/schemas/Bytes' OrganizationID: type: string OrganizationConfig: type: object description: Configuration values for an organization. Note that some values are read-only. properties: pricing_tier: $ref: '#/components/schemas/PricingTier' from_email: type: string description: 'The email address from which authentication emails are sent. Empty means SlashID''s default e-mail address will be used. This is set during onboarding. ' from_phone_number_sms: type: string description: 'The phone number from which authentication SMS messages are sent. Empty means SlashID''s default phone numbers will be used. This is set during onboarding. ' token_duration: type: integer description: The number of seconds before a token expires. groups_claim_name: type: string description: The name of the JWT claim holding the list of groups for the authenticated user identified in the token. example: dev.slashid.groups requires_manual_approval: type: boolean description: If true, new users are deactivated until the organization admin sets the person's `active` field. deny_self_registration: type: boolean description: If true, new users can only be created by the organization admin allowed_factor_methods: type: array description: 'Only allow authentication using the specified factor methods. Empty means all supported factors are enabled. This configuration doesn''t affect API and DirectID authentications. ' example: - sms_link - email_link - webauthn items: $ref: '#/components/schemas/FactorMethod' authn_link_allowed_redirect_uris: type: array maxItems: 8 description: 'The URIs to which users can be redirected after authenticating with an email/SMS link. It can''t be an IP, nor contain query parameters or fragments. We advise that it''s an HTTPS URI but we don''t require it. Custom schemes are allowed. ' example: - https://slashid.com - http://localhost:8080/a-path - com.slashid://example items: type: string new_person_handle_patterns: type: array description: Only allow registration of new persons with a handle matching one of the patterns. example: - '*@example.com' - +1* items: $ref: '#/components/schemas/GlobPattern' sudo_mode_duration: type: integer description: The number of seconds, after users authenticate, during which they can perform sensitive actions. authn_redirect_page_ui_config: $ref: '#/components/schemas/AuthnRedirectPageUIConfig' canonical_identity_ai_matching_enabled: type: boolean description: 'If true (default), uses AI-based matching for canonical identities which provides higher accuracy through fuzzy matching and semantic analysis. If false, uses deterministic field-level matching based on exact email/identifier matches, which may result in more missed matches and require more manual management. ' default: true required: - from_email - from_phone_number_sms - token_duration - groups_claim_name - requires_manual_approval - deny_self_registration - allowed_factor_methods - authn_link_allowed_redirect_uris - new_person_handle_patterns - sudo_mode_duration APIResponseError: type: object properties: httpcode: type: integer message: type: string APIMeta: type: object properties: pagination: $ref: '#/components/schemas/APIPagination' cursor_pagination: $ref: '#/components/schemas/APICursorPagination' AttributeBucket: type: object description: An attribute bucket with access settings required: - name - sharing_scope - end_user_permissions properties: name: type: string description: The name of the attribute bucket sharing_scope: $ref: '#/components/schemas/AttributeSharingScope' owner_organization_id: $ref: '#/components/schemas/OrganizationID' end_user_permissions: $ref: '#/components/schemas/AttributePermissions' OrganizationConfigPatchRequest: type: object description: Request for updating organization configuration values. properties: token_duration: type: integer description: The number of seconds before a token expires groups_claim_name: type: string description: The name of the JWT claim holding the list of groups for the authenticated user identified in the token example: dev.slashid.groups requires_manual_approval: type: boolean description: If true, new users are deactivated until the organization admin sets the person's `active` field. deny_self_registration: type: boolean description: If true, new users can only be created by the organization admin allowed_factor_methods: type: array description: 'Only allow authentication using the specified factor methods. Empty means all supported factors are enabled. This configuration doesn''t affect API and DirectID authentications. ' example: - sms_link - email_link - webauthn items: $ref: '#/components/schemas/FactorMethod' authn_link_allowed_redirect_uris: type: array description: 'The URIs to where users can be redirected after authenticating with an email/SMS link. ' items: type: string new_person_handle_patterns: type: array description: Only allow registration of new persons with a handle matching one of the patterns example: - '*@example.com' - +1* items: $ref: '#/components/schemas/GlobPattern' sudo_mode_duration: type: integer description: The number of seconds, after users authenticate, during which they can perform sensitive actions. Negative values will revert this property to its default (15 minutes). authn_redirect_page_ui_config: $ref: '#/components/schemas/AuthnRedirectPageUIConfig' canonical_identity_ai_matching_enabled: type: boolean description: 'Enable or disable AI-based canonical identity matching. When disabled, falls back to deterministic field-level matching. ' AuthnRedirectPageUIConfig: type: object additionalProperties: true description: UI configuration for the hosted page users are redirected to after clicking a magic link or password reset link. OrganizationsPutAPIKeyResponse: type: object required: - api_key properties: api_key: type: string SuborganizationCreateRequest: type: object properties: sub_org_name: type: string admins: type: array items: $ref: '#/components/schemas/PersonHandle' persons_org_id: $ref: '#/components/schemas/OrganizationID' groups_org_id: $ref: '#/components/schemas/OrganizationID' inherit_rbac_pools: type: boolean description: "This setting determines how permissions and roles are managed for a suborganization.\nWhen `inherit_rbac_pools` is set to false: - The suborganization has its own independent permissions and roles. - Permissions and roles can be fully customized for this suborganization.\nWhen `inherit_rbac_pools` is set to true: - Permissions:\n - Inherited from the nearest ancestor with 'inherit_rbac_pools' set to false.\n - Read-only for this suborganization.\n - Cannot be modified within this suborganization.\n\n- Roles:\n - Scoped to each organization, including this suborganization.\n - Visible across all organizations within the inheritance pool.\n - Roles from other organizations can be assigned to users in this suborganization.\n\nNote: - Individual role and permission assignments are not inherited. - This setting cannot be changed after the suborganization is created.\n" required: - sub_org_name - admins Organization: type: object properties: id: $ref: '#/components/schemas/OrganizationID' parent_id: $ref: '#/components/schemas/OrganizationID' org_name: type: string tenant_name: type: string required: - id - org_name - tenant_name securitySchemes: ApiKeyAuth: description: Authorizes the request with the organization's API Key. x-svc-um-api: true type: apiKey in: header name: SlashID-API-Key OAuth2ClientIdSecret: description: Authorizes the request with a client ID/client secret pair type: http scheme: basic OAuth2AccessTokenBearer: description: Authorizes the request with an Access Token for the current user. type: http scheme: bearer bearerFormat: opaque