diff --git a/.gitignore b/.gitignore index 44d1a937d..bc7d15e53 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,7 @@ # build output dist/ + + # generated types .astro/ .idea diff --git a/netlify.toml b/netlify.toml index 7a9852de3..55746d9d8 100644 --- a/netlify.toml +++ b/netlify.toml @@ -83,8 +83,18 @@ [headers.values] Cache-Control = "public, max-age=86400, s-maxage=86400, stale-while-revalidate=604800" -# Markdown API reference: 1 hour (generated from spec) +# Markdown API references: 1 hour (generated from spec) [[headers]] for = "/apis.md" + [headers.values] + Cache-Control = "public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400" + +[[headers]] + for = "/agentkit/apis.md" + [headers.values] + Cache-Control = "public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400" + +[[headers]] + for = "/saaskit/apis.md" [headers.values] Cache-Control = "public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400" \ No newline at end of file diff --git a/openapi/agentkit.yaml b/openapi/agentkit.yaml new file mode 100644 index 000000000..44c8f68ae --- /dev/null +++ b/openapi/agentkit.yaml @@ -0,0 +1,125 @@ +info: + title: AgentKit APIs + description: | + # Overview + + The AgentKit API gives your AI agents authenticated access to third-party apps — sending emails, reading calendars, creating tickets, querying databases, and more. Your agent calls a tool; Scalekit handles the OAuth flow, token storage, and API call. + + **Base URLs:** + + ``` + https://{your-subdomain}.scalekit.dev (Development) + https://{your-subdomain}.scalekit.com (Production) + ``` + + ## Quickstart + + ### 1. Get an access token + + Use your API credentials from the [Scalekit Dashboard](https://app.scalekit.com) → **Developers → Settings → API Credentials**. + + ```sh + curl -X POST https:///oauth/token \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'client_id={client_id}' \ + -d 'client_secret={client_secret}' \ + -d 'grant_type=client_credentials' + ``` + + ### 2. List connected accounts + + ```sh + curl https:///api/v1/connected_accounts \ + -H 'Authorization: Bearer {access_token}' + ``` + + ### 3. Execute a tool on behalf of a user + + ```sh + curl -X POST https:///api/v1/execute_tool \ + -H 'Authorization: Bearer {access_token}' \ + -H 'Content-Type: application/json' \ + -d '{ + "connected_account_id": "{connected_account_id}", + "tool_name": "gmail_fetch_emails", + "tool_input": { "max_results": 5 } + }' + ``` + + ## SDKs + + ```sh + npm install @scalekit-sdk/node # Node.js + pip install scalekit-sdk-python # Python + ``` + + For the full product guide, see the [AgentKit documentation](https://docs.scalekit.com/agentkit/quickstart/). + + --- + + Looking for SSO, SCIM, directory sync, or user management APIs? See the [SaaSKit API reference](https://docs.scalekit.com/saaskit/apis/). For the complete endpoint list across both products, see [All APIs](https://docs.scalekit.com/apis/). + contact: + name: Scalekit Inc + url: https://scalekit.com + email: support@scalekit.com + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0 + version: 1.0.0 +paths: + /api/v1/connected_accounts: + $ref: paths/api_v1_connected_accounts.yaml + /api/v1/connected_accounts/auth: + $ref: paths/api_v1_connected_accounts_auth.yaml + /api/v1/connected_accounts/details: + $ref: paths/api_v1_connected_accounts_details.yaml + /api/v1/connected_accounts/magic_link: + $ref: paths/api_v1_connected_accounts_magic_link.yaml + /api/v1/connected_accounts/user/verify: + $ref: paths/api_v1_connected_accounts_user_verify.yaml + /api/v1/connected_accounts:delete: + $ref: paths/api_v1_connected_accounts:delete.yaml + /api/v1/connected_accounts:search: + $ref: paths/api_v1_connected_accounts:search.yaml + /api/v1/execute_tool: + $ref: paths/api_v1_execute_tool.yaml +tags: + - description: >- + Manage connected accounts for third-party integrations and OAuth + connections. Connected accounts represent authenticated access to external + services like Google, Notion, Slack, and other applications. + name: Connected Accounts +externalDocs: + description: AgentKit Docs + url: https://docs.scalekit.com/agentkit/quickstart/ +openapi: 3.1.1 +servers: + - url: https://$SCALEKIT_ENVIRONMENT_URL +components: + securitySchemes: + oauth2: + type: oauth2 + flows: + clientCredentials: + tokenUrl: https://$SCALEKIT_ENVIRONMENT_URL/oauth/token + scopes: + '': No scope required for client credentials flow +security: + - oauth2: [] +webhooks: + connected_account.created: + $ref: webhooks/connected_account.created.yaml + connected_account.updated: + $ref: webhooks/connected_account.updated.yaml + connected_account.deleted: + $ref: webhooks/connected_account.deleted.yaml + connected_account.magic_link_generated: + $ref: webhooks/connected_account.magic_link_generated.yaml + connected_account.oauth_tokens_fetched: + $ref: webhooks/connected_account.oauth_tokens_fetched.yaml + connected_account.token_refresh_succeeded: + $ref: webhooks/connected_account.token_refresh_succeeded.yaml + connected_account.token_refresh_failed: + $ref: webhooks/connected_account.token_refresh_failed.yaml + connected_account.oauth_succeeded: + $ref: webhooks/connected_account.oauth_succeeded.yaml \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_connections/get.go b/openapi/code_samples/go/api_v1_connections/get.go new file mode 100644 index 000000000..22a647360 --- /dev/null +++ b/openapi/code_samples/go/api_v1_connections/get.go @@ -0,0 +1,9 @@ +// List connections by organization id +connections, err := scalekitClient.Connection().ListConnections( + ctx, + organizationId +) + +// List connections by domain +connections, err := scalekitClient.Connection().ListConnectionsByDomain(ctx, + domain) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_memberships_organizations_{organization_id}_users_{id}/post.go b/openapi/code_samples/go/api_v1_memberships_organizations_{organization_id}_users_{id}/post.go new file mode 100644 index 000000000..31db829df --- /dev/null +++ b/openapi/code_samples/go/api_v1_memberships_organizations_{organization_id}_users_{id}/post.go @@ -0,0 +1,21 @@ +func main() { + scalekitClient := scalekit.NewScalekitClient( + os.Getenv("SCALEKIT_ENV_URL"), + os.Getenv("SCALEKIT_CLIENT_ID"), + os.Getenv("SCALEKIT_CLIENT_SECRET"), + ) + membership := &usersv1.CreateMembership{ + Roles: []*usersv1.Role{{Name: "admin"}}, + Metadata: map[string]string{ + "department": "engineering", + "location": "nyc-office", + }, + } + resp, + err := scalekitClient.User().CreateMembership( + context.Background(), "org_123", + "usr_123", membership, false) + if err != nil { + panic(err) + } +} \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations/get.go b/openapi/code_samples/go/api_v1_organizations/get.go new file mode 100644 index 000000000..49b2b7b3f --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations/get.go @@ -0,0 +1,6 @@ +organizations, err := scalekitClient.Organization.ListOrganizations( + ctx, + &scalekit.ListOrganizationOptions{ + PageSize: 10, + } +) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations/post.go b/openapi/code_samples/go/api_v1_organizations/post.go new file mode 100644 index 000000000..cb7a278db --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations/post.go @@ -0,0 +1,7 @@ +organization, err := ScalekitClient.Organization.CreateOrganization( + ctx, + name, + scalekit.CreateOrganizationOptions{ + ExternalID: "externalId", + }, +) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{id}/delete.go b/openapi/code_samples/go/api_v1_organizations_{id}/delete.go new file mode 100644 index 000000000..e7ccf1f9d --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{id}/delete.go @@ -0,0 +1,4 @@ +err := scalekitClient.Organization.DeleteOrganization( + ctx, + organizationId +) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{id}/get.go b/openapi/code_samples/go/api_v1_organizations_{id}/get.go new file mode 100644 index 000000000..96625b3ef --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{id}/get.go @@ -0,0 +1,10 @@ +scalekitClient := scalekit.NewScalekitClient( + , + , + +) + +organization, err := scalekitClient.Organization.GetOrganization( + ctx, + organizationId +) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{id}/patch.go b/openapi/code_samples/go/api_v1_organizations_{id}/patch.go new file mode 100644 index 000000000..b1fcba6c4 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{id}/patch.go @@ -0,0 +1,8 @@ +organization, err := scalekitClient.Organization.UpdateOrganization( + ctx, + organizationId, + &scalekit.UpdateOrganization{ + DisplayName: "displayName", + ExternalId: "externalId", + }, +) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{id}_portal_links/put.go b/openapi/code_samples/go/api_v1_organizations_{id}_portal_links/put.go new file mode 100644 index 000000000..8eef92c0a --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{id}_portal_links/put.go @@ -0,0 +1,4 @@ +link, err := scalekitClient.Organization.GeneratePortalLink( + ctx, + organizationId +) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{id}_settings/patch.go b/openapi/code_samples/go/api_v1_organizations_{id}_settings/patch.go new file mode 100644 index 000000000..a9b890bd4 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{id}_settings/patch.go @@ -0,0 +1,26 @@ +settings := OrganizationSettings{ + + Features: []Feature{ + + { + + Name: "sso", + + Enabled: true, + + }, + + { + + Name: "dir_sync", + + Enabled: true, + + }, + + }, + + } + + +organization,err := scalekitClient.Organization().UpdateOrganizationSettings(ctx, organizationId, settings) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{org_id}_roles/get.go b/openapi/code_samples/go/api_v1_organizations_{org_id}_roles/get.go new file mode 100644 index 000000000..820a2e302 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{org_id}_roles/get.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.Role().ListOrganizationRoles(ctx, "org_123") +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{org_id}_roles/post.go b/openapi/code_samples/go/api_v1_organizations_{org_id}_roles/post.go new file mode 100644 index 000000000..81df936a3 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{org_id}_roles/post.go @@ -0,0 +1,13 @@ +resp, err := scalekitClient.Role().CreateOrganizationRole(ctx, "org_123", &rolesv1.CreateOrganizationRole{ + + Name: "org_admin", + + DisplayName: "Org Admin", + + Description: proto.String("Organization-scoped role"), // optional + + Extends: proto.String("base_role_name"), // optional + + Permissions: []string{"perm.read", "perm.write"}, // optional + +}) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{org_id}_roles:set_defaults/patch.go b/openapi/code_samples/go/api_v1_organizations_{org_id}_roles:set_defaults/patch.go new file mode 100644 index 000000000..8faba5c73 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{org_id}_roles:set_defaults/patch.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.Role().UpdateDefaultOrganizationRoles(ctx, "org_123", "org_member") +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{org_id}_roles_{role_name}/delete.go b/openapi/code_samples/go/api_v1_organizations_{org_id}_roles_{role_name}/delete.go new file mode 100644 index 000000000..9ab3732bb --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{org_id}_roles_{role_name}/delete.go @@ -0,0 +1,6 @@ +// Basic delete +err := scalekitClient.Role().DeleteOrganizationRole(ctx, "org_123", "org_role_admin") +if err != nil { /* handle err */ } + +// With reassignment +err = scalekitClient.Role().DeleteOrganizationRole(ctx, "org_123", "org_role_admin", "org_role_member") \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{org_id}_roles_{role_name}/get.go b/openapi/code_samples/go/api_v1_organizations_{org_id}_roles_{role_name}/get.go new file mode 100644 index 000000000..105c1070d --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{org_id}_roles_{role_name}/get.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.Role().GetOrganizationRole(ctx, "org_123", "org_admin") +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{org_id}_roles_{role_name}/put.go b/openapi/code_samples/go/api_v1_organizations_{org_id}_roles_{role_name}/put.go new file mode 100644 index 000000000..0c9bb2592 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{org_id}_roles_{role_name}/put.go @@ -0,0 +1,6 @@ +resp, err := scalekitClient.Role().UpdateOrganizationRole(ctx, "org_123", "org_admin", &rolesv1.UpdateRole{ + DisplayName: "Org Admin (Updated)", + Description: "Updated org role description", +}) +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_connections_{id}/delete.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_connections_{id}/delete.go new file mode 100644 index 000000000..a9c1346e9 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_connections_{id}/delete.go @@ -0,0 +1,5 @@ +err := scalekitClient.Connection.DeleteConnection( + ctx, + organizationId, + connectionId, +) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_connections_{id}/get.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_connections_{id}/get.go new file mode 100644 index 000000000..dc1551311 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_connections_{id}/get.go @@ -0,0 +1,5 @@ +connection, err := scalekitClient.Connection.GetConnection( + ctx, + organizationId, + connectionId, +) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.go new file mode 100644 index 000000000..374d31c2f --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.go @@ -0,0 +1,5 @@ +err := scalekitClient.Connection.DisableConnection( + ctx, + organizationId, + connectionId, +) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.go new file mode 100644 index 000000000..9ad85db00 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.go @@ -0,0 +1,5 @@ +err := scalekitClient.Connection.EnableConnection( + ctx, + organizationId, + connectionId, +) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories/get.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories/get.go new file mode 100644 index 000000000..516985813 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories/get.go @@ -0,0 +1 @@ +directories,err := scalekitClient.Directory().ListDirectories(ctx, organizationId) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.go new file mode 100644 index 000000000..0cd1b3693 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.go @@ -0,0 +1,10 @@ +options := &ListDirectoryGroupsOptions{ + + PageSize: 10, + + PageToken:"", + + } + + +directoryGroups, err := scalekitClient.Directory().ListDirectoryGroups(ctx, organizationId, directoryId, options) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.go new file mode 100644 index 000000000..9f2f1a111 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.go @@ -0,0 +1,9 @@ +options := &ListDirectoryUsersOptions{ + + PageSize: 10, + + PageToken: "", + + } + +directoryUsers,err := scalekitClient.Directory().ListDirectoryUsers(ctx, organizationId, directoryId, options) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories_{id}/get.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories_{id}/get.go new file mode 100644 index 000000000..ce14642b7 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories_{id}/get.go @@ -0,0 +1 @@ +directory, err := scalekitClient.Directory().GetDirectory(ctx, organizationId, directoryId) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.go new file mode 100644 index 000000000..5f22bf297 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.go @@ -0,0 +1 @@ +disable,err := scalekitClient.Directory().DisableDirectory(ctx, organizationId, directoryId) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.go new file mode 100644 index 000000000..d5aeae801 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.go @@ -0,0 +1 @@ +enable,err := scalekitClient.Directory().EnableDirectory(ctx, organizationId, directoryId) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_domains/get.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_domains/get.go new file mode 100644 index 000000000..973c552bc --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_domains/get.go @@ -0,0 +1,3 @@ +domains, err := scalekitClient.Domain().ListDomains(ctx, "org_id", &scalekit.ListDomainOptions{ +DomainType: "ORGANIZATION_DOMAIN", +}) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_domains/post.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_domains/post.go new file mode 100644 index 000000000..ab60651b8 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_domains/post.go @@ -0,0 +1,5 @@ +domain, err := scalekitClient.Domain().CreateDomain(ctx, "org_id", "example.com", &scalekit.CreateDomainOptions{ + + DomainType: "ORGANIZATION_DOMAIN", + + }) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_domains_{id}/delete.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_domains_{id}/delete.go new file mode 100644 index 000000000..0371086bf --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_domains_{id}/delete.go @@ -0,0 +1 @@ +err = scalekitClient.Domain().DeleteDomain(ctx, "dom_123", "org_123") \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_domains_{id}/get.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_domains_{id}/get.go new file mode 100644 index 000000000..982265fd7 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_domains_{id}/get.go @@ -0,0 +1 @@ +domain, err := scalekitClient.Domain().GetDomain(ctx, "dom_123", "org_123") \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_users/get.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_users/get.go new file mode 100644 index 000000000..21ca6da26 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_users/get.go @@ -0,0 +1,4 @@ +list, + err := scalekitClient.User().ListOrganizationUsers(ctx, "org_123", &scalekit.ListUsersOptions{PageSize: +50}) if err != nil { /* handle error */ } +fmt.Println(list.Users) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_users/post.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_users/post.go new file mode 100644 index 000000000..95802aa2b --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_users/post.go @@ -0,0 +1,15 @@ +newUser := &usersv1.CreateUser{ + Email: "user@example.com", + ExternalId: "ext_12345a67b89c", + Metadata: map[string]string{ + "department": "engineering", + "location": "nyc-office", + }, + UserProfile: &usersv1.CreateUserProfile{ + FirstName: "John", + LastName: "Doe", + }, +} +cuResp, + err := scalekitClient.User().CreateUserAndMembership(ctx, "org_123", +newUser, false) if err != nil { /* handle error */ } \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.go new file mode 100644 index 000000000..ea53c57d8 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.go @@ -0,0 +1,5 @@ +resp, err := scalekitClient.User().ListUserPermissions(ctx, "org_123", "usr_123") +if err != nil { + // handle error +} +permissions := resp.Permissions \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.go b/openapi/code_samples/go/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.go new file mode 100644 index 000000000..95a735cc0 --- /dev/null +++ b/openapi/code_samples/go/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.go @@ -0,0 +1,5 @@ +resp, err := scalekitClient.User().ListUserRoles(ctx, "org_123", "usr_123") +if err != nil { + // handle error +} +roles := resp.Roles \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_passwordless_email_resend/post.go b/openapi/code_samples/go/api_v1_passwordless_email_resend/post.go new file mode 100644 index 000000000..6dc61c628 --- /dev/null +++ b/openapi/code_samples/go/api_v1_passwordless_email_resend/post.go @@ -0,0 +1,9 @@ +resendResponse, err := scalekitClient.Passwordless().ResendPasswordlessEmail( + ctx, + authRequestId, +) + +if err != nil { + // Handle error + return +} \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_passwordless_email_send/post.go b/openapi/code_samples/go/api_v1_passwordless_email_send/post.go new file mode 100644 index 000000000..3e5800d7d --- /dev/null +++ b/openapi/code_samples/go/api_v1_passwordless_email_send/post.go @@ -0,0 +1,22 @@ +templateType := scalekit.TemplateTypeSignin +response, err := scalekitClient.Passwordless().SendPasswordlessEmail( + ctx, + "john.doe@example.com", + &scalekit.SendPasswordlessOptions{ + Template: &templateType, + ExpiresIn: 100, + MagiclinkAuthUri: "https://www.google.com", + TemplateVariables: map[string]string{ + "employeeID": "EMP523", + "teamName": "Alpha Team", + "supportEmail": "support@yourcompany.com", + }, + }, +) + +if err != nil { + // Handle error + return +} + +authRequestId := response.AuthRequestId \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_passwordless_email_verify/post.go b/openapi/code_samples/go/api_v1_passwordless_email_verify/post.go new file mode 100644 index 000000000..1276cb70f --- /dev/null +++ b/openapi/code_samples/go/api_v1_passwordless_email_verify/post.go @@ -0,0 +1,29 @@ +// Verify with OTP code +verifyResponse, err := scalekitClient.Passwordless().VerifyPasswordlessEmail( + ctx, + &scalekit.VerifyPasswordlessOptions{ + Code: "123456", // OTP code + AuthRequestId: authRequestId, + }, +) + +if err != nil { + // Handle error + return +} + +// Verify with magic link token +verifyResponse, err := scalekitClient.Passwordless().VerifyPasswordlessEmail( + ctx, + &scalekit.VerifyPasswordlessOptions{ + LinkToken: linkToken, // Magic link token + }, +) + +if err != nil { + // Handle error + return +} + +// User verified successfully +userEmail := verifyResponse.Email \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_permissions/get.go b/openapi/code_samples/go/api_v1_permissions/get.go new file mode 100644 index 000000000..e131a75c3 --- /dev/null +++ b/openapi/code_samples/go/api_v1_permissions/get.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.Permission().ListPermissions(ctx) +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_permissions/post.go b/openapi/code_samples/go/api_v1_permissions/post.go new file mode 100644 index 000000000..3cbb9035e --- /dev/null +++ b/openapi/code_samples/go/api_v1_permissions/post.go @@ -0,0 +1,9 @@ +resp, err := scalekitClient.Permission().CreatePermission(ctx, &rolesv1.CreatePermission{ + + Name: "read:users", + + Description: "Allows reading users", + +}) +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_permissions_{permission_name}/delete.go b/openapi/code_samples/go/api_v1_permissions_{permission_name}/delete.go new file mode 100644 index 000000000..1f7a17e29 --- /dev/null +++ b/openapi/code_samples/go/api_v1_permissions_{permission_name}/delete.go @@ -0,0 +1,2 @@ +err := scalekitClient.Permission().DeletePermission(ctx, "read:users") +if err != nil { /* handle err */ } \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_permissions_{permission_name}/get.go b/openapi/code_samples/go/api_v1_permissions_{permission_name}/get.go new file mode 100644 index 000000000..2f6fecca1 --- /dev/null +++ b/openapi/code_samples/go/api_v1_permissions_{permission_name}/get.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.Permission().GetPermission(ctx, "read:users") +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_permissions_{permission_name}/put.go b/openapi/code_samples/go/api_v1_permissions_{permission_name}/put.go new file mode 100644 index 000000000..0649bf21e --- /dev/null +++ b/openapi/code_samples/go/api_v1_permissions_{permission_name}/put.go @@ -0,0 +1,6 @@ +resp, err := scalekitClient.Permission().UpdatePermission(ctx, "read:users", &rolesv1.CreatePermission{ + Name: "read:users", + Description: "Allows reading user resources", +}) +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_roles/get.go b/openapi/code_samples/go/api_v1_roles/get.go new file mode 100644 index 000000000..a137ea638 --- /dev/null +++ b/openapi/code_samples/go/api_v1_roles/get.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.Role().ListRoles(ctx) +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_roles/post.go b/openapi/code_samples/go/api_v1_roles/post.go new file mode 100644 index 000000000..d88e009bd --- /dev/null +++ b/openapi/code_samples/go/api_v1_roles/post.go @@ -0,0 +1,13 @@ +resp, err := scalekitClient.Role().CreateRole(ctx, &rolesv1.CreateRole{ + + Name: "admin", + + DisplayName: "Admin", + + Description: "Environment-level role", + + Extends: proto.String("base_role"), // optional + + Permissions: []string{"read:users"}, // optional + +}) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_roles:set_defaults/patch.go b/openapi/code_samples/go/api_v1_roles:set_defaults/patch.go new file mode 100644 index 000000000..50f057634 --- /dev/null +++ b/openapi/code_samples/go/api_v1_roles:set_defaults/patch.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.Role().UpdateDefaultRoles(ctx, "member") +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_roles_{role_name}/delete.go b/openapi/code_samples/go/api_v1_roles_{role_name}/delete.go new file mode 100644 index 000000000..0429cbb6a --- /dev/null +++ b/openapi/code_samples/go/api_v1_roles_{role_name}/delete.go @@ -0,0 +1,6 @@ +// Basic delete +err := scalekitClient.Role().DeleteRole(ctx, "admin") +if err != nil { /* handle err */ } + +// With reassignment +err = scalekitClient.Role().DeleteRole(ctx, "admin", "member") \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_roles_{role_name}/get.go b/openapi/code_samples/go/api_v1_roles_{role_name}/get.go new file mode 100644 index 000000000..38c9c8ea5 --- /dev/null +++ b/openapi/code_samples/go/api_v1_roles_{role_name}/get.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.Role().GetRole(ctx, "admin") +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_roles_{role_name}/put.go b/openapi/code_samples/go/api_v1_roles_{role_name}/put.go new file mode 100644 index 000000000..cbf06e489 --- /dev/null +++ b/openapi/code_samples/go/api_v1_roles_{role_name}/put.go @@ -0,0 +1,6 @@ +resp, err := scalekitClient.Role().UpdateRole(ctx, "admin", &rolesv1.UpdateRole{ + DisplayName: "Admin (Updated)", + Description: "Updated description", +}) +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_roles_{role_name}_dependents/get.go b/openapi/code_samples/go/api_v1_roles_{role_name}_dependents/get.go new file mode 100644 index 000000000..17825dc14 --- /dev/null +++ b/openapi/code_samples/go/api_v1_roles_{role_name}_dependents/get.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.Role().ListDependentRoles(ctx, "admin") +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_roles_{role_name}_permissions/get.go b/openapi/code_samples/go/api_v1_roles_{role_name}_permissions/get.go new file mode 100644 index 000000000..0c10380f0 --- /dev/null +++ b/openapi/code_samples/go/api_v1_roles_{role_name}_permissions/get.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.Permission().ListRolePermissions(ctx, "admin") +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_roles_{role_name}_permissions/post.go b/openapi/code_samples/go/api_v1_roles_{role_name}_permissions/post.go new file mode 100644 index 000000000..3f7c800ec --- /dev/null +++ b/openapi/code_samples/go/api_v1_roles_{role_name}_permissions/post.go @@ -0,0 +1 @@ +resp, err := scalekitClient.Permission().AddPermissionsToRole(ctx, "role_admin", []string{"perm.read", "perm.write"}) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_roles_{role_name}_permissions_{permission_name}/delete.go b/openapi/code_samples/go/api_v1_roles_{role_name}_permissions_{permission_name}/delete.go new file mode 100644 index 000000000..4a42a624e --- /dev/null +++ b/openapi/code_samples/go/api_v1_roles_{role_name}_permissions_{permission_name}/delete.go @@ -0,0 +1,2 @@ +err := scalekitClient.Permission().RemovePermissionFromRole(ctx, "admin", "read:users") +if err != nil { /* handle err */ } \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_roles_{role_name}_users:count/get.go b/openapi/code_samples/go/api_v1_roles_{role_name}_users:count/get.go new file mode 100644 index 000000000..bfda52dec --- /dev/null +++ b/openapi/code_samples/go/api_v1_roles_{role_name}_users:count/get.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.Role().GetRoleUsersCount(ctx, "admin") +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_sessions_{session_id}/get.go b/openapi/code_samples/go/api_v1_sessions_{session_id}/get.go new file mode 100644 index 000000000..626f36c91 --- /dev/null +++ b/openapi/code_samples/go/api_v1_sessions_{session_id}/get.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.Session().GetSession(ctx, "ses_123456789") +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_sessions_{session_id}_revoke/post.go b/openapi/code_samples/go/api_v1_sessions_{session_id}_revoke/post.go new file mode 100644 index 000000000..0a0b2d7bd --- /dev/null +++ b/openapi/code_samples/go/api_v1_sessions_{session_id}_revoke/post.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.Session().RevokeSession(ctx, "ses_123456789") +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_users/get.go b/openapi/code_samples/go/api_v1_users/get.go new file mode 100644 index 000000000..2657fcca4 --- /dev/null +++ b/openapi/code_samples/go/api_v1_users/get.go @@ -0,0 +1 @@ +all, err := scalekitClient.User().ListUsers(ctx, &scalekit.ListUsersOptions{PageSize: 100}) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_users_{id}/delete.go b/openapi/code_samples/go/api_v1_users_{id}/delete.go new file mode 100644 index 000000000..2c8bc47c4 --- /dev/null +++ b/openapi/code_samples/go/api_v1_users_{id}/delete.go @@ -0,0 +1,4 @@ +if err := scalekitClient.User().DeleteUser(ctx, + "usr_123"); err != nil { + panic(err) +} \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_users_{id}/get.go b/openapi/code_samples/go/api_v1_users_{id}/get.go new file mode 100644 index 000000000..c8f329787 --- /dev/null +++ b/openapi/code_samples/go/api_v1_users_{id}/get.go @@ -0,0 +1,5 @@ +resp, err := scalekitClient.User().GetUser(ctx, "usr_123456") +if err != nil { + // handle error +} +user := resp.User \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_users_{id}/patch.go b/openapi/code_samples/go/api_v1_users_{id}/patch.go new file mode 100644 index 000000000..ce50c7d9e --- /dev/null +++ b/openapi/code_samples/go/api_v1_users_{id}/patch.go @@ -0,0 +1,10 @@ +upd := &usersv1.UpdateUser{ + UserProfile: &usersv1.UpdateUserProfile{ + FirstName: "John", + LastName: "Smith", + }, + Metadata: map[string]string{ + "department": "sales", + }, +} +scalekitClient.User().UpdateUser(ctx, "usr_123", upd) \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_users_{user_id}_sessions/get.go b/openapi/code_samples/go/api_v1_users_{user_id}_sessions/get.go new file mode 100644 index 000000000..1a4ce7df2 --- /dev/null +++ b/openapi/code_samples/go/api_v1_users_{user_id}_sessions/get.go @@ -0,0 +1,15 @@ +// Basic usage +resp, err := scalekitClient.Session().GetUserSessions(ctx, "user_123", 0, "", nil) +if err != nil { /* handle err */ } + +// With pagination and filtering +// import "time", sessionsv1 "...", "google.golang.org/protobuf/types/known/timestamppb" +startTime, _ := time.Parse(time.RFC3339, "2024-01-01T00:00:00Z") +endTime, _ := time.Parse(time.RFC3339, "2024-12-31T23:59:59Z") +filter := &sessionsv1.UserSessionFilter{ + Status: []string{"ACTIVE"}, + StartTime: timestamppb.New(startTime), + EndTime: timestamppb.New(endTime), +} +resp, err := scalekitClient.Session().GetUserSessions(ctx, "user_123", 10, "next_page_token", filter) +if err != nil { /* handle err */ } \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_users_{user_id}_sessions_revoke/post.go b/openapi/code_samples/go/api_v1_users_{user_id}_sessions_revoke/post.go new file mode 100644 index 000000000..9c1f5e2d2 --- /dev/null +++ b/openapi/code_samples/go/api_v1_users_{user_id}_sessions_revoke/post.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.Session().RevokeAllUserSessions(ctx, "user_123") +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_webauthn_credentials/get.go b/openapi/code_samples/go/api_v1_webauthn_credentials/get.go new file mode 100644 index 000000000..3f2ef0c06 --- /dev/null +++ b/openapi/code_samples/go/api_v1_webauthn_credentials/get.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.WebAuthn().ListCredentials(ctx, "user_123") +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_webauthn_credentials_{credential_id}/delete.go b/openapi/code_samples/go/api_v1_webauthn_credentials_{credential_id}/delete.go new file mode 100644 index 000000000..1aa33aece --- /dev/null +++ b/openapi/code_samples/go/api_v1_webauthn_credentials_{credential_id}/delete.go @@ -0,0 +1,3 @@ +resp, err := scalekitClient.WebAuthn().DeleteCredential(ctx, "wac_123") +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/go/api_v1_webauthn_credentials_{credential_id}/patch.go b/openapi/code_samples/go/api_v1_webauthn_credentials_{credential_id}/patch.go new file mode 100644 index 000000000..ed57438a5 --- /dev/null +++ b/openapi/code_samples/go/api_v1_webauthn_credentials_{credential_id}/patch.go @@ -0,0 +1,7 @@ +resp, err := scalekitClient.WebAuthn().UpdateCredential( + ctx, + "wac_123", + "Work Laptop Passkey", +) +if err != nil { /* handle err */ } +_ = resp \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_connections/get.java b/openapi/code_samples/java/api_v1_connections/get.java new file mode 100644 index 000000000..90e89f935 --- /dev/null +++ b/openapi/code_samples/java/api_v1_connections/get.java @@ -0,0 +1,7 @@ +// List connections by organization id +ListConnectionsResponse response = scalekitClient.connections( + ).listConnections(organizationId); + +// List connections by domain +ListConnectionsResponse response = scalekitClient.connections( + ).listConnectionsByDomain("your-domain.com"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_memberships_organizations_{organization_id}_users_{id}/post.java b/openapi/code_samples/java/api_v1_memberships_organizations_{organization_id}_users_{id}/post.java new file mode 100644 index 000000000..fc049148b --- /dev/null +++ b/openapi/code_samples/java/api_v1_memberships_organizations_{organization_id}_users_{id}/post.java @@ -0,0 +1,22 @@ +import com.scalekit.ScalekitClient; +import com.scalekit.api.UserClient; +import com.scalekit.grpc.scalekit.v1.users.*; +ScalekitClient scalekitClient = new ScalekitClient( + System.getenv("SCALEKIT_ENV_URL"), + System.getenv("SCALEKIT_CLIENT_ID"), + System.getenv("SCALEKIT_CLIENT_SECRET") +); +UserClient users = scalekitClient.users(); +CreateMembershipRequest membershipReq = CreateMemb + ershipRequest.newBuilder() + .setMembership( + CreateMembership.newBuilder() + .addRoles(Role.newBuilder( + ).setName("admin").build()) + .putMetadata("department", "engineering") + .putMetadata("location", "nyc-office") + .build()) + .build(); +CreateMembershipResponse res = users. + createMembership("org_123", "usr_123", + membershipReq); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations/get.java b/openapi/code_samples/java/api_v1_organizations/get.java new file mode 100644 index 000000000..95a8d773d --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations/get.java @@ -0,0 +1 @@ +ListOrganizationsResponse organizations = scalekitClient.organizations().listOrganizations(10, ""); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations/post.java b/openapi/code_samples/java/api_v1_organizations/post.java new file mode 100644 index 000000000..ca1e50c32 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations/post.java @@ -0,0 +1,5 @@ +CreateOrganization createOrganization = CreateOrganization.newBuilder() + .setDisplayName("Test Org") + .build(); + +Organization createdOrganization = scalekitClient.organizations().create(createOrganization); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{id}/delete.java b/openapi/code_samples/java/api_v1_organizations_{id}/delete.java new file mode 100644 index 000000000..59c4d43c1 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{id}/delete.java @@ -0,0 +1,7 @@ +ScalekitClient scalekitClient = new ScalekitClient( + "", + "", + "" +); + +scalekitClient.organizations().deleteById(organizationId); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{id}/get.java b/openapi/code_samples/java/api_v1_organizations_{id}/get.java new file mode 100644 index 000000000..a296d3e22 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{id}/get.java @@ -0,0 +1,7 @@ +ScalekitClient scalekitClient = new ScalekitClient( + "", + "", + "" +); + +Organization organization = scalekitClient.organizations().getById(organizationId); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{id}/patch.java b/openapi/code_samples/java/api_v1_organizations_{id}/patch.java new file mode 100644 index 000000000..f15bded87 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{id}/patch.java @@ -0,0 +1,5 @@ +UpdateOrganization updateOrganization = UpdateOrganization.newBuilder() + .setDisplayName("Updated Organization Name") + .build(); + +Organization updatedOrganizationById = scalekitClient.organizations().updateById(organizationId, updateOrganization); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{id}_portal_links/put.java b/openapi/code_samples/java/api_v1_organizations_{id}_portal_links/put.java new file mode 100644 index 000000000..3b497d7ac --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{id}_portal_links/put.java @@ -0,0 +1,3 @@ +Link portalLink = client + .organizations() + .generatePortalLink(organizationId, Arrays.asList(Feature.sso, Feature.dir_sync)); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{id}_settings/patch.java b/openapi/code_samples/java/api_v1_organizations_{id}_settings/patch.java new file mode 100644 index 000000000..24a49be6b --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{id}_settings/patch.java @@ -0,0 +1,13 @@ +OrganizationSettingsFeature featureSSO = OrganizationSettingsFeature.newBuilder() + .setName("sso") + .setEnabled(true) + .build(); + +OrganizationSettingsFeature featureDirectorySync = OrganizationSettingsFeature.newBuilder() + .setName("dir_sync") + .setEnabled(true) + .build(); + +updatedOrganization = scalekitClient.organizations() + .updateOrganizationSettings(organization.getId(), List.of(featureSSO, +featureDirectorySync)); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{org_id}_roles/get.java b/openapi/code_samples/java/api_v1_organizations_{org_id}_roles/get.java new file mode 100644 index 000000000..d7bbdbc51 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{org_id}_roles/get.java @@ -0,0 +1 @@ +ListOrganizationRolesResponse res = scalekitClient.roles().listOrganizationRoles("org_123"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{org_id}_roles/post.java b/openapi/code_samples/java/api_v1_organizations_{org_id}_roles/post.java new file mode 100644 index 000000000..3aab3ce1e --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{org_id}_roles/post.java @@ -0,0 +1,16 @@ +CreateOrganizationRoleResponse res = scalekitClient.roles().createOrganizationRole( + "org_123", + CreateOrganizationRoleRequest.newBuilder() + .setOrgId("org_123") + .setRole( + CreateOrganizationRole.newBuilder() + .setName("org_admin") + .setDisplayName("Org Admin") + .setDescription("Organization-scoped role") + .setExtends("base_role_name") // optional + .addPermissions("perm.read") // optional + .addPermissions("perm.write") // optional + .build() + ) + .build() +); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{org_id}_roles:set_defaults/patch.java b/openapi/code_samples/java/api_v1_organizations_{org_id}_roles:set_defaults/patch.java new file mode 100644 index 000000000..6ad5e5aad --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{org_id}_roles:set_defaults/patch.java @@ -0,0 +1,6 @@ +UpdateDefaultOrganizationRolesResponse res = scalekitClient.roles().updateDefaultOrganizationRoles( + "org_123", + UpdateDefaultOrganizationRolesRequest.newBuilder() + .setDefaultMemberRole("org_member") + .build() +); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{org_id}_roles_{role_name}/delete.java b/openapi/code_samples/java/api_v1_organizations_{org_id}_roles_{role_name}/delete.java new file mode 100644 index 000000000..b22e47a99 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{org_id}_roles_{role_name}/delete.java @@ -0,0 +1,5 @@ +// Basic delete +scalekitClient.roles().deleteOrganizationRole("org_123", "org_role_admin"); + +// With reassignment +scalekitClient.roles().deleteOrganizationRole("org_123", "org_role_admin", "org_role_member"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{org_id}_roles_{role_name}/get.java b/openapi/code_samples/java/api_v1_organizations_{org_id}_roles_{role_name}/get.java new file mode 100644 index 000000000..de30b4e32 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{org_id}_roles_{role_name}/get.java @@ -0,0 +1 @@ +GetOrganizationRoleResponse res = scalekitClient.roles().getOrganizationRole("org_123", "org_admin"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{org_id}_roles_{role_name}/put.java b/openapi/code_samples/java/api_v1_organizations_{org_id}_roles_{role_name}/put.java new file mode 100644 index 000000000..6844b2306 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{org_id}_roles_{role_name}/put.java @@ -0,0 +1,12 @@ +UpdateOrganizationRoleResponse res = scalekitClient.roles().updateOrganizationRole( + "org_123", + "org_admin", + UpdateOrganizationRoleRequest.newBuilder() + .setRole( + UpdateRole.newBuilder() + .setDisplayName("Org Admin (Updated)") + .setDescription("Updated org role description") + .build() + ) + .build() +); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_connections_{id}/delete.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_connections_{id}/delete.java new file mode 100644 index 000000000..c4ae1774d --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_connections_{id}/delete.java @@ -0,0 +1 @@ +scalekitClient.connections().deleteConnection(connectionId, organizationId); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_connections_{id}/get.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_connections_{id}/get.java new file mode 100644 index 000000000..b06590ec0 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_connections_{id}/get.java @@ -0,0 +1 @@ +Connection connection = scalekitClient.connections().getConnectionById(connectionId, organizationId); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.java new file mode 100644 index 000000000..59b327624 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.java @@ -0,0 +1 @@ +ToggleConnectionResponse response = scalekitClient.connections().disableConnection(connectionId, organizationId); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.java new file mode 100644 index 000000000..061134de9 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.java @@ -0,0 +1 @@ +ToggleConnectionResponse response = scalekitClient.connections().enableConnection(connectionId, organizationId); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories/get.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories/get.java new file mode 100644 index 000000000..de94a430d --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories/get.java @@ -0,0 +1 @@ +ListDirectoriesResponse response = scalekitClient.directories().listDirectories(organizationId); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.java new file mode 100644 index 000000000..92a5e88f3 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.java @@ -0,0 +1,9 @@ +var options = ListDirectoryResourceOptions.builder() + .pageSize(10) + .pageToken("") + .includeDetail(true) + .build(); + +ListDirectoryGroupsResponse groupsResponse = scalekitClient + .directories() + .listDirectoryGroups(directory.getId(), organizationId, options); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.java new file mode 100644 index 000000000..325d74863 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.java @@ -0,0 +1,9 @@ +var options = ListDirectoryResourceOptions.builder() + .pageSize(10) + .pageToken("") + .includeDetail(true) + .build(); + +ListDirectoryUsersResponse usersResponse = scalekitClient + .directories() + .listDirectoryUsers(directory.getId(), organizationId, options); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories_{id}/get.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories_{id}/get.java new file mode 100644 index 000000000..ddbcd88f9 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories_{id}/get.java @@ -0,0 +1 @@ +Directory directory = scalekitClient.directories().getDirectory(directoryId, organizationId); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.java new file mode 100644 index 000000000..6165265e3 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.java @@ -0,0 +1,3 @@ +ToggleDirectoryResponse disableResponse = scalekitClient + .directories() + .disableDirectory(directoryId, organizationId); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.java new file mode 100644 index 000000000..5cdb277c8 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.java @@ -0,0 +1,3 @@ +ToggleDirectoryResponse enableResponse = client + .directories() + .enableDirectory(directoryId, organizationId); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_domains/get.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_domains/get.java new file mode 100644 index 000000000..cc247a78d --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_domains/get.java @@ -0,0 +1 @@ +List domains = scalekitClient.domains().listDomainsByOrganizationId("org_id", "ORGANIZATION_DOMAIN"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_domains/post.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_domains/post.java new file mode 100644 index 000000000..082e45d88 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_domains/post.java @@ -0,0 +1,9 @@ +CreateDomainRequest request = CreateDomainRequest.newBuilder() + .setOrganizationId(organization.getId()) + .setDomain(CreateDomain.newBuilder() + .setDomain("example.com") + .setDomainType("ORGANIZATION_DOMAIN") + .build()) + .build(); + +Domain domain = scalekitClient.domains().createDomain(request); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_domains_{id}/delete.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_domains_{id}/delete.java new file mode 100644 index 000000000..907835521 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_domains_{id}/delete.java @@ -0,0 +1 @@ +scalekitClient.domains().deleteDomain(organization.getId(), domain.getId()); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_domains_{id}/get.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_domains_{id}/get.java new file mode 100644 index 000000000..536d17424 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_domains_{id}/get.java @@ -0,0 +1 @@ +Domain domain = scalekitClient.domains().getDomainById("org_123", "dom_123"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_users/get.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_users/get.java new file mode 100644 index 000000000..2db8b03ae --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_users/get.java @@ -0,0 +1,6 @@ +ListOrganizationUsersRequest listReq = ListOrganiz + ationUsersRequest.newBuilder() + .setPageSize(50) + .build(); +ListOrganizationUsersResponse list = users. + listOrganizationUsers("org_123", listReq); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_users/post.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_users/post.java new file mode 100644 index 000000000..eb0311c5f --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_users/post.java @@ -0,0 +1,18 @@ +CreateUser createUser = CreateUser.newBuilder() + .setEmail("user@example.com") + .setExternalId("ext_12345a67b89c") + .putMetadata("department", "engineering") + .putMetadata("location", "nyc-office") + .setUserProfile( + CreateUserProfile.newBuilder() + .setFirstName("John") + .setLastName("Doe") + .build()) + .build(); +CreateUserAndMembershipRequest cuReq = CreateUserA + ndMembershipRequest.newBuilder() + .setUser(createUser) + .build(); +CreateUserAndMembershipResponse cuResp = users. + createUserAndMembership("org_123", cuReq); +System.out.println(cuResp.getUser().getId()); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.java new file mode 100644 index 000000000..c38563bbc --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.java @@ -0,0 +1,2 @@ +ListUserPermissionsResponse resp = scalekitClient.users().listUserPermissions("org_123", "usr_123"); +List permissions = resp.getPermissionsList(); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.java b/openapi/code_samples/java/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.java new file mode 100644 index 000000000..74d811e36 --- /dev/null +++ b/openapi/code_samples/java/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.java @@ -0,0 +1,2 @@ +ListUserRolesResponse resp = scalekitClient.users().listUserRoles("org_123", "usr_123"); +List roles = resp.getRolesList(); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_passwordless_email_resend/post.java b/openapi/code_samples/java/api_v1_passwordless_email_resend/post.java new file mode 100644 index 000000000..b55c2a611 --- /dev/null +++ b/openapi/code_samples/java/api_v1_passwordless_email_resend/post.java @@ -0,0 +1 @@ +SendPasswordlessResponse resendResponse = passwordlessClient.resendPasswordlessEmail(authRequestId); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_passwordless_email_send/post.java b/openapi/code_samples/java/api_v1_passwordless_email_send/post.java new file mode 100644 index 000000000..434a88fac --- /dev/null +++ b/openapi/code_samples/java/api_v1_passwordless_email_send/post.java @@ -0,0 +1,18 @@ +TemplateType templateType = TemplateType.SIGNIN; +Map templateVariables = new HashMap<>(); +templateVariables.put("employeeID", "EMP523"); +templateVariables.put("teamName", "Alpha Team"); +templateVariables.put("supportEmail", "support@yourcompany.com"); + +SendPasswordlessOptions options = new SendPasswordlessOptions(); +options.setTemplate(templateType); +options.setExpiresIn(100); +options.setMagiclinkAuthUri("https://www.example.com"); +options.setTemplateVariables(templateVariables); + +SendPasswordlessResponse response = passwordlessClient.sendPasswordlessEmail( + "john.doe@example.com", + options +); + +String authRequestId = response.getAuthRequestId(); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_passwordless_email_verify/post.java b/openapi/code_samples/java/api_v1_passwordless_email_verify/post.java new file mode 100644 index 000000000..a77896808 --- /dev/null +++ b/openapi/code_samples/java/api_v1_passwordless_email_verify/post.java @@ -0,0 +1,18 @@ +// Verify with OTP code +VerifyPasswordlessOptions verifyOptions = new VerifyPasswordlessOptions(); +verifyOptions.setCode("123456"); // OTP code +verifyOptions.setAuthRequestId(authRequestId); + +VerifyPasswordLessResponse verifyResponse = passwordlessClient.verifyPasswordlessEmail(verifyOptions); + +// User verified successfully +String userEmail = verifyResponse.getEmail(); + +// Verify with magic link token +VerifyPasswordlessOptions verifyOptions = new VerifyPasswordlessOptions(); +verifyOptions.setLinkToken(linkToken); // Magic link token + +VerifyPasswordLessResponse verifyResponse = passwordlessClient.verifyPasswordlessEmail(verifyOptions); + +// User verified successfully +String userEmail = verifyResponse.getEmail(); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_permissions/get.java b/openapi/code_samples/java/api_v1_permissions/get.java new file mode 100644 index 000000000..67506a367 --- /dev/null +++ b/openapi/code_samples/java/api_v1_permissions/get.java @@ -0,0 +1 @@ +ListPermissionsResponse res = scalekitClient.permissions().listPermissions(); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_permissions/post.java b/openapi/code_samples/java/api_v1_permissions/post.java new file mode 100644 index 000000000..a4a2e3049 --- /dev/null +++ b/openapi/code_samples/java/api_v1_permissions/post.java @@ -0,0 +1,10 @@ +CreatePermissionResponse res = scalekitClient.permissions().createPermission( + CreatePermissionRequest.newBuilder() + .setPermission( + CreatePermission.newBuilder() + .setName("read:users") + .setDescription("Allows reading users") + .build() + ) + .build() +); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_permissions_{permission_name}/delete.java b/openapi/code_samples/java/api_v1_permissions_{permission_name}/delete.java new file mode 100644 index 000000000..1b8f6319a --- /dev/null +++ b/openapi/code_samples/java/api_v1_permissions_{permission_name}/delete.java @@ -0,0 +1 @@ +scalekitClient.permissions().deletePermission("read:users"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_permissions_{permission_name}/get.java b/openapi/code_samples/java/api_v1_permissions_{permission_name}/get.java new file mode 100644 index 000000000..2b1dd3552 --- /dev/null +++ b/openapi/code_samples/java/api_v1_permissions_{permission_name}/get.java @@ -0,0 +1 @@ +GetPermissionResponse res = scalekitClient.permissions().getPermission("read:users"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_permissions_{permission_name}/put.java b/openapi/code_samples/java/api_v1_permissions_{permission_name}/put.java new file mode 100644 index 000000000..8dd133ba4 --- /dev/null +++ b/openapi/code_samples/java/api_v1_permissions_{permission_name}/put.java @@ -0,0 +1,11 @@ +UpdatePermissionResponse res = scalekitClient.permissions().updatePermission( + "read:users", + UpdatePermissionRequest.newBuilder() + .setPermission( + CreatePermission.newBuilder() + .setName("read:users") + .setDescription("Allows reading user resources") + .build() + ) + .build() +); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_roles/get.java b/openapi/code_samples/java/api_v1_roles/get.java new file mode 100644 index 000000000..8c8e9cf81 --- /dev/null +++ b/openapi/code_samples/java/api_v1_roles/get.java @@ -0,0 +1 @@ +ListRolesResponse res = scalekitClient.roles().listRoles(); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_roles/post.java b/openapi/code_samples/java/api_v1_roles/post.java new file mode 100644 index 000000000..244afad2b --- /dev/null +++ b/openapi/code_samples/java/api_v1_roles/post.java @@ -0,0 +1,13 @@ +CreateRoleResponse res = scalekitClient.roles().createRole( + CreateRoleRequest.newBuilder() + .setRole( + CreateRole.newBuilder() + .setName("admin") + .setDisplayName("Admin") + .setDescription("Environment-level role") + // .setExtends("base_role") // optional + // .addPermissions("read:users") // optional + .build() + ) + .build() +); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_roles:set_defaults/patch.java b/openapi/code_samples/java/api_v1_roles:set_defaults/patch.java new file mode 100644 index 000000000..bf87123a6 --- /dev/null +++ b/openapi/code_samples/java/api_v1_roles:set_defaults/patch.java @@ -0,0 +1,5 @@ +UpdateDefaultRolesResponse res = scalekitClient.roles().updateDefaultRoles( + UpdateDefaultRolesRequest.newBuilder() + .setDefaultMemberRole("member") + .build() +); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_roles_{role_name}/delete.java b/openapi/code_samples/java/api_v1_roles_{role_name}/delete.java new file mode 100644 index 000000000..d2f42b8d7 --- /dev/null +++ b/openapi/code_samples/java/api_v1_roles_{role_name}/delete.java @@ -0,0 +1,5 @@ +// Basic delete +scalekitClient.roles().deleteRole("admin"); + +// With reassignment +scalekitClient.roles().deleteRole("admin", "member"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_roles_{role_name}/get.java b/openapi/code_samples/java/api_v1_roles_{role_name}/get.java new file mode 100644 index 000000000..bc9607567 --- /dev/null +++ b/openapi/code_samples/java/api_v1_roles_{role_name}/get.java @@ -0,0 +1 @@ +GetRoleResponse res = scalekitClient.roles().getRole("admin"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_roles_{role_name}/put.java b/openapi/code_samples/java/api_v1_roles_{role_name}/put.java new file mode 100644 index 000000000..74e1fe62c --- /dev/null +++ b/openapi/code_samples/java/api_v1_roles_{role_name}/put.java @@ -0,0 +1,11 @@ +UpdateRoleResponse res = scalekitClient.roles().updateRole( + "admin", + UpdateRoleRequest.newBuilder() + .setRole( + UpdateRole.newBuilder() + .setDisplayName("Admin (Updated)") + .setDescription("Updated description") + .build() + ) + .build() +); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_roles_{role_name}_dependents/get.java b/openapi/code_samples/java/api_v1_roles_{role_name}_dependents/get.java new file mode 100644 index 000000000..e1dfffecd --- /dev/null +++ b/openapi/code_samples/java/api_v1_roles_{role_name}_dependents/get.java @@ -0,0 +1 @@ +ListDependentRolesResponse res = scalekitClient.roles().listDependentRoles("admin"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_roles_{role_name}_permissions/get.java b/openapi/code_samples/java/api_v1_roles_{role_name}_permissions/get.java new file mode 100644 index 000000000..95f9604a1 --- /dev/null +++ b/openapi/code_samples/java/api_v1_roles_{role_name}_permissions/get.java @@ -0,0 +1 @@ +ListRolePermissionsResponse res = scalekitClient.permissions().listRolePermissions("admin"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_roles_{role_name}_permissions/post.java b/openapi/code_samples/java/api_v1_roles_{role_name}_permissions/post.java new file mode 100644 index 000000000..2cf6d9113 --- /dev/null +++ b/openapi/code_samples/java/api_v1_roles_{role_name}_permissions/post.java @@ -0,0 +1,7 @@ +AddPermissionsToRoleResponse res = scalekitClient.permissions().addPermissionsToRole( + "role_admin", + AddPermissionsToRoleRequest.newBuilder() + .addPermissionNames("perm.read") + .addPermissionNames("perm.write") + .build() +); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_roles_{role_name}_permissions_{permission_name}/delete.java b/openapi/code_samples/java/api_v1_roles_{role_name}_permissions_{permission_name}/delete.java new file mode 100644 index 000000000..c804a404d --- /dev/null +++ b/openapi/code_samples/java/api_v1_roles_{role_name}_permissions_{permission_name}/delete.java @@ -0,0 +1 @@ +scalekitClient.permissions().removePermissionFromRole("admin", "read:users"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_roles_{role_name}_users:count/get.java b/openapi/code_samples/java/api_v1_roles_{role_name}_users:count/get.java new file mode 100644 index 000000000..916e222d7 --- /dev/null +++ b/openapi/code_samples/java/api_v1_roles_{role_name}_users:count/get.java @@ -0,0 +1 @@ +GetRoleUsersCountResponse res = scalekitClient.roles().getRoleUsersCount("admin"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_sessions_{session_id}/get.java b/openapi/code_samples/java/api_v1_sessions_{session_id}/get.java new file mode 100644 index 000000000..8444ad0d1 --- /dev/null +++ b/openapi/code_samples/java/api_v1_sessions_{session_id}/get.java @@ -0,0 +1 @@ +SessionDetails res = scalekitClient.sessions().getSession("ses_123456789"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_sessions_{session_id}_revoke/post.java b/openapi/code_samples/java/api_v1_sessions_{session_id}_revoke/post.java new file mode 100644 index 000000000..6a1afbcc5 --- /dev/null +++ b/openapi/code_samples/java/api_v1_sessions_{session_id}_revoke/post.java @@ -0,0 +1 @@ +RevokeSessionResponse res = scalekitClient.sessions().revokeSession("ses_123456789"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_users/get.java b/openapi/code_samples/java/api_v1_users/get.java new file mode 100644 index 000000000..5f51daef4 --- /dev/null +++ b/openapi/code_samples/java/api_v1_users/get.java @@ -0,0 +1,3 @@ +ListUsersRequest lur = ListUsersRequest. + newBuilder().setPageSize(100).build(); +ListUsersResponse allUsers = users.listUsers(lur); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_users_{id}/delete.java b/openapi/code_samples/java/api_v1_users_{id}/delete.java new file mode 100644 index 000000000..ad44101d3 --- /dev/null +++ b/openapi/code_samples/java/api_v1_users_{id}/delete.java @@ -0,0 +1 @@ +users.deleteUser("usr_123"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_users_{id}/get.java b/openapi/code_samples/java/api_v1_users_{id}/get.java new file mode 100644 index 000000000..5035ec171 --- /dev/null +++ b/openapi/code_samples/java/api_v1_users_{id}/get.java @@ -0,0 +1,2 @@ +GetUserResponse resp = scalekitClient.users().getUser("usr_123456"); +User user = resp.getUser(); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_users_{id}/patch.java b/openapi/code_samples/java/api_v1_users_{id}/patch.java new file mode 100644 index 000000000..fb851b284 --- /dev/null +++ b/openapi/code_samples/java/api_v1_users_{id}/patch.java @@ -0,0 +1,11 @@ +UpdateUser upd = UpdateUser.newBuilder() + .setUserProfile( + UpdateUserProfile.newBuilder() + .setFirstName("John") + .setLastName("Smith") + .build()) + .putMetadata("department", "sales") + .build(); +UpdateUserRequest updReq = UpdateUserRequest. + newBuilder().setUser(upd).build(); +users.updateUser("usr_123", updReq); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_users_{user_id}_sessions/get.java b/openapi/code_samples/java/api_v1_users_{user_id}_sessions/get.java new file mode 100644 index 000000000..5446b24d6 --- /dev/null +++ b/openapi/code_samples/java/api_v1_users_{user_id}_sessions/get.java @@ -0,0 +1,11 @@ +// Basic usage +UserSessionDetails res = scalekitClient.sessions().getUserSessions("user_123", null, null, null); + +// With pagination and filtering +// import UserSessionFilter, Timestamp, Instant +UserSessionFilter filter = UserSessionFilter.newBuilder() + .addStatus("ACTIVE") + .setStartTime(Timestamp.newBuilder().setSeconds(Instant.parse("2024-01-01T00:00:00Z").getEpochSecond()).build()) + .setEndTime(Timestamp.newBuilder().setSeconds(Instant.parse("2024-12-31T23:59:59Z").getEpochSecond()).build()) + .build(); +UserSessionDetails res = scalekitClient.sessions().getUserSessions("user_123", 10, "next_page_token", filter); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_users_{user_id}_sessions_revoke/post.java b/openapi/code_samples/java/api_v1_users_{user_id}_sessions_revoke/post.java new file mode 100644 index 000000000..420c65bd6 --- /dev/null +++ b/openapi/code_samples/java/api_v1_users_{user_id}_sessions_revoke/post.java @@ -0,0 +1 @@ +RevokeAllUserSessionsResponse res = scalekitClient.sessions().revokeAllUserSessions("user_123"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_webauthn_credentials/get.java b/openapi/code_samples/java/api_v1_webauthn_credentials/get.java new file mode 100644 index 000000000..f924d0919 --- /dev/null +++ b/openapi/code_samples/java/api_v1_webauthn_credentials/get.java @@ -0,0 +1 @@ +ListCredentialsResponse res = scalekitClient.webauthn().listCredentials("user_123"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_webauthn_credentials_{credential_id}/delete.java b/openapi/code_samples/java/api_v1_webauthn_credentials_{credential_id}/delete.java new file mode 100644 index 000000000..7f851f325 --- /dev/null +++ b/openapi/code_samples/java/api_v1_webauthn_credentials_{credential_id}/delete.java @@ -0,0 +1 @@ +DeleteCredentialResponse res = scalekitClient.webauthn().deleteCredential("wac_123"); \ No newline at end of file diff --git a/openapi/code_samples/java/api_v1_webauthn_credentials_{credential_id}/patch.java b/openapi/code_samples/java/api_v1_webauthn_credentials_{credential_id}/patch.java new file mode 100644 index 000000000..7977f57e2 --- /dev/null +++ b/openapi/code_samples/java/api_v1_webauthn_credentials_{credential_id}/patch.java @@ -0,0 +1,2 @@ +UpdateCredentialResponse res = scalekitClient.webauthn() + .updateCredential("wac_123", "Work Laptop Passkey"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_connections/get.js b/openapi/code_samples/javascript/api_v1_connections/get.js new file mode 100644 index 000000000..189b5d6fd --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_connections/get.js @@ -0,0 +1,5 @@ +// List connections by organization id +const connections = await scalekit.connection.listConnections(organizationId); + +// List connections by domain +const connections = await scalekit.connection.listConnectionsByDomain(domain); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_memberships_organizations_{organization_id}_users_{id}/post.js b/openapi/code_samples/javascript/api_v1_memberships_organizations_{organization_id}_users_{id}/post.js new file mode 100644 index 000000000..41c7f58dd --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_memberships_organizations_{organization_id}_users_{id}/post.js @@ -0,0 +1,13 @@ +import { ScalekitClient } from "@scalekit-sdk/node"; +const scalekit = new ScalekitClient( + process.env.SCALEKIT_ENV_URL, + process.env.SCALEKIT_CLIENT_ID, + process.env.SCALEKIT_CLIENT_SECRET +); +await scalekit.user.createMembership("org_123", "usr_123", { + roles: ["admin"], + metadata: { + department: "engineering", + location: "nyc-office", + }, +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations/get.js b/openapi/code_samples/javascript/api_v1_organizations/get.js new file mode 100644 index 000000000..a1536a0ea --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations/get.js @@ -0,0 +1,3 @@ +const organizations = await scalekit.organization.listOrganization({ + pageSize: 10, +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations/post.js b/openapi/code_samples/javascript/api_v1_organizations/post.js new file mode 100644 index 000000000..06f259945 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations/post.js @@ -0,0 +1,5 @@ +const organization = await scalekit.organization.createOrganization(name, { + + externalId: "externalId", + +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{id}/delete.js b/openapi/code_samples/javascript/api_v1_organizations_{id}/delete.js new file mode 100644 index 000000000..d4979bb48 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{id}/delete.js @@ -0,0 +1 @@ +await scalekit.organization.deleteOrganization(organizationId); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{id}/get.js b/openapi/code_samples/javascript/api_v1_organizations_{id}/get.js new file mode 100644 index 000000000..d5312ba8f --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{id}/get.js @@ -0,0 +1,7 @@ +const scalekit = new ScalekitClient( + , + , + +); + +const organization = await scalekit.organization.getOrganization(organization_id); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{id}/patch.js b/openapi/code_samples/javascript/api_v1_organizations_{id}/patch.js new file mode 100644 index 000000000..91173f31d --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{id}/patch.js @@ -0,0 +1,4 @@ +const organization = await scalekit.organization.updateOrganization(organization_id, { + displayName: 'displayName', + externalId: 'externalId', +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{id}_portal_links/put.js b/openapi/code_samples/javascript/api_v1_organizations_{id}_portal_links/put.js new file mode 100644 index 000000000..7f494a458 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{id}_portal_links/put.js @@ -0,0 +1 @@ +const link = await scalekit.organization.generatePortalLink(organizationId); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{id}_settings/patch.js b/openapi/code_samples/javascript/api_v1_organizations_{id}_settings/patch.js new file mode 100644 index 000000000..434b0a10a --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{id}_settings/patch.js @@ -0,0 +1,14 @@ +const settings = { + features: [ + { + name: 'sso', + enabled: true, + }, + { + name: 'dir_sync', + enabled: true, + }, + ], +}; + +await scalekit.organization.updateOrganizationSettings('', settings); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles/get.js b/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles/get.js new file mode 100644 index 000000000..95545a870 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles/get.js @@ -0,0 +1 @@ +const res = await scalekit.role.listOrganizationRoles("org_123"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles/post.js b/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles/post.js new file mode 100644 index 000000000..8d7ea86b1 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles/post.js @@ -0,0 +1,7 @@ +await scalekit.role.createOrganizationRole("org_123", { + name: "org_admin", + displayName: "Org Admin", + description: "Organization-scoped role", + extends: "base_role_name", // optional + permissions: ["perm.read", "perm.write"] // optional +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles:set_defaults/patch.js b/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles:set_defaults/patch.js new file mode 100644 index 000000000..7b94a1239 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles:set_defaults/patch.js @@ -0,0 +1,3 @@ +const res = await scalekit.role.updateDefaultOrganizationRoles("org_123", { + defaultMemberRole: "org_member" +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles_{role_name}/delete.js b/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles_{role_name}/delete.js new file mode 100644 index 000000000..1fedbc835 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles_{role_name}/delete.js @@ -0,0 +1,5 @@ +// Basic delete +await scalekit.role.deleteOrganizationRole("org_123", "org_role_admin"); + +// With reassignment +await scalekit.role.deleteOrganizationRole("org_123", "org_role_admin", "org_role_member"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles_{role_name}/get.js b/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles_{role_name}/get.js new file mode 100644 index 000000000..ae77d7b72 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles_{role_name}/get.js @@ -0,0 +1 @@ +const res = await scalekit.role.getOrganizationRole("org_123", "org_admin"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles_{role_name}/put.js b/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles_{role_name}/put.js new file mode 100644 index 000000000..158cc8b6f --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{org_id}_roles_{role_name}/put.js @@ -0,0 +1,4 @@ +await scalekit.role.updateOrganizationRole("org_123", "org_admin", { + displayName: "Org Admin (Updated)", + description: "Updated org role description" +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}/delete.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}/delete.js new file mode 100644 index 000000000..fd99c27df --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}/delete.js @@ -0,0 +1 @@ +await scalekit.connection.deleteConnection(organizationId, connectionId); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}/get.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}/get.js new file mode 100644 index 000000000..8a74d8a56 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}/get.js @@ -0,0 +1,4 @@ +const connection = await scalekit.connection.getConnection( + organizationId, + connectionId +); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.js new file mode 100644 index 000000000..965b901ab --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.js @@ -0,0 +1 @@ +await scalekit.connection.disableConnection(organizationId, connectionId); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.js new file mode 100644 index 000000000..4767aeda3 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.js @@ -0,0 +1 @@ +await scalekit.connection.enableConnection(organizationId, connectionId); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories/get.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories/get.js new file mode 100644 index 000000000..1055c7e94 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories/get.js @@ -0,0 +1 @@ +await scalekit.directory.listDirectories(''); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.js new file mode 100644 index 000000000..d1dff2a72 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.js @@ -0,0 +1,4 @@ +const { groups } = await scalekit.directory.listDirectoryGroups( + '', + '' +); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.js new file mode 100644 index 000000000..1abf88acc --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.js @@ -0,0 +1,4 @@ +const { users } = await scalekit.directory.listDirectoryUsers( + '', + '' +); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories_{id}/get.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories_{id}/get.js new file mode 100644 index 000000000..7e71af729 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories_{id}/get.js @@ -0,0 +1,4 @@ +const { directory } = await scalekit.directory.getDirectory( + organizationId, + directoryId +); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.js new file mode 100644 index 000000000..8792268bb --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.js @@ -0,0 +1,4 @@ +await scalekit.directory.disableDirectory( + '', + '' +); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.js new file mode 100644 index 000000000..1010f8fe6 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.js @@ -0,0 +1 @@ +await scalekit.directory.enableDirectory('', ''); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_domains/get.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_domains/get.js new file mode 100644 index 000000000..2ab43cae2 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_domains/get.js @@ -0,0 +1,10 @@ +// List all domains in an organization +const response = await scalekit.domain.listDomains(organizationId, { + domainType: "ORGANIZATION_DOMAIN" +}); + +// Domain object contains: +// - id: Domain identifier +// - domain: Domain name +// - organizationId: Owning organization +// - domainType: Configuration type \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_domains/post.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_domains/post.js new file mode 100644 index 000000000..fcad5153a --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_domains/post.js @@ -0,0 +1,8 @@ +// Add a new domain to an organization +const response = await scalekit.createDomain("org-123", "example.com", { + + // Domain type: controls user authentication and email validation + + domainType: "ORGANIZATION_DOMAIN", + +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_domains_{id}/delete.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_domains_{id}/delete.js new file mode 100644 index 000000000..b48da72f5 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_domains_{id}/delete.js @@ -0,0 +1,3 @@ +// Remove a domain from an organization +// Caution: Deletion is permanent and may affect user access +const response = await scalekit.domain.deleteDomain(organizationId, domainId); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_domains_{id}/get.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_domains_{id}/get.js new file mode 100644 index 000000000..0be598555 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_domains_{id}/get.js @@ -0,0 +1,8 @@ +// Fetch details of a specific domain +const response = await scalekit.domain.getDomain(organizationId, domainId); + +// Domain object properties: +// - id: Domain identifier +// - domain: Domain name +// - organizationId: Owning organization +// - domainType: Domain configuration type \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_users/get.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_users/get.js new file mode 100644 index 000000000..dc4bcd998 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_users/get.js @@ -0,0 +1,5 @@ +const response = await scalekit.user. + listOrganizationUsers("org_123", { + pageSize: 50, +}); +console.log(response.users); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_users/post.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_users/post.js new file mode 100644 index 000000000..709063cd5 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_users/post.js @@ -0,0 +1,12 @@ +const { + user } = await scalekit.user. + createUserAndMembership("org_123", { + email: "user@example.com", + externalId: "ext_12345a67b89c", + metadata: { department: "engineering", + location: "nyc-office" }, + userProfile: { + firstName: "John", + lastName: "Doe", + }, +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.js new file mode 100644 index 000000000..06c92cfbe --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.js @@ -0,0 +1 @@ +const { permissions } = await scalekit.user.listUserPermissions("org_123", "usr_123"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.js b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.js new file mode 100644 index 000000000..f0aee56db --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.js @@ -0,0 +1 @@ +const { roles } = await scalekit.user.listUserRoles("org_123", "usr_123"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_passwordless_email_resend/post.js b/openapi/code_samples/javascript/api_v1_passwordless_email_resend/post.js new file mode 100644 index 000000000..2a1a22e22 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_passwordless_email_resend/post.js @@ -0,0 +1,6 @@ +const { authRequestId } = sendResponse; +const resendResponse = await scalekit.passwordless.resendPasswordlessEmail( + + authRequestId + +); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_passwordless_email_send/post.js b/openapi/code_samples/javascript/api_v1_passwordless_email_send/post.js new file mode 100644 index 000000000..da1d521fe --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_passwordless_email_send/post.js @@ -0,0 +1,13 @@ +const response = await scalekit.passwordless.sendPasswordlessEmail( + "john.doe@example.com", + { + template: "SIGNIN", + expiresIn: 100, + magiclinkAuthUri: "https://www.google.com", + templateVariables: { + employeeID: "EMP523", + teamName: "Alpha Team", + supportEmail: "support@yourcompany.com", + }, + } +); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_passwordless_email_verify/post.js b/openapi/code_samples/javascript/api_v1_passwordless_email_verify/post.js new file mode 100644 index 000000000..e313910ae --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_passwordless_email_verify/post.js @@ -0,0 +1,14 @@ +const { authRequestId } = sendResponse; +const verifyResponse = await scalekit.passwordless.verifyPasswordlessEmail( + + // Verification Code (OTP) + + { code: "123456" }, + + // Magic Link Token + + { linkToken: link_token }, + + authRequestId + +); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_permissions/get.js b/openapi/code_samples/javascript/api_v1_permissions/get.js new file mode 100644 index 000000000..f5200df33 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_permissions/get.js @@ -0,0 +1 @@ +const res = await scalekit.permission.listPermissions(); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_permissions/post.js b/openapi/code_samples/javascript/api_v1_permissions/post.js new file mode 100644 index 000000000..907acd375 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_permissions/post.js @@ -0,0 +1,4 @@ +await scalekit.permission.createPermission({ + name: "read:users", + description: "Allows reading users" +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_permissions_{permission_name}/delete.js b/openapi/code_samples/javascript/api_v1_permissions_{permission_name}/delete.js new file mode 100644 index 000000000..1daa686da --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_permissions_{permission_name}/delete.js @@ -0,0 +1 @@ +await scalekit.permission.deletePermission("read:users"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_permissions_{permission_name}/get.js b/openapi/code_samples/javascript/api_v1_permissions_{permission_name}/get.js new file mode 100644 index 000000000..e6b68a06e --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_permissions_{permission_name}/get.js @@ -0,0 +1 @@ +const res = await scalekit.permission.getPermission("read:users"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_permissions_{permission_name}/put.js b/openapi/code_samples/javascript/api_v1_permissions_{permission_name}/put.js new file mode 100644 index 000000000..ce0a30657 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_permissions_{permission_name}/put.js @@ -0,0 +1,4 @@ +await scalekit.permission.updatePermission("read:users", { + name: "read:users", + description: "Allows reading user resources" +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_roles/get.js b/openapi/code_samples/javascript/api_v1_roles/get.js new file mode 100644 index 000000000..cef04c487 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_roles/get.js @@ -0,0 +1 @@ +const res = await scalekit.role.listRoles(); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_roles/post.js b/openapi/code_samples/javascript/api_v1_roles/post.js new file mode 100644 index 000000000..9d7e51ada --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_roles/post.js @@ -0,0 +1,7 @@ +await scalekit.role.createRole({ + name: "admin", + displayName: "Admin", + description: "Environment-level role", + extends: "base_role", // optional + permissions: ["read:users"] // optional +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_roles:set_defaults/patch.js b/openapi/code_samples/javascript/api_v1_roles:set_defaults/patch.js new file mode 100644 index 000000000..d1d4b6765 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_roles:set_defaults/patch.js @@ -0,0 +1,3 @@ +const res = await scalekit.role.updateDefaultRoles({ + defaultMemberRole: "member" +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_roles_{role_name}/delete.js b/openapi/code_samples/javascript/api_v1_roles_{role_name}/delete.js new file mode 100644 index 000000000..f9015c2c4 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_roles_{role_name}/delete.js @@ -0,0 +1,5 @@ +// Basic delete +await scalekit.role.deleteRole("admin"); + +// With reassignment +await scalekit.role.deleteRole("admin", "member"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_roles_{role_name}/get.js b/openapi/code_samples/javascript/api_v1_roles_{role_name}/get.js new file mode 100644 index 000000000..f2083053f --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_roles_{role_name}/get.js @@ -0,0 +1 @@ +const res = await scalekit.role.getRole("admin"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_roles_{role_name}/put.js b/openapi/code_samples/javascript/api_v1_roles_{role_name}/put.js new file mode 100644 index 000000000..d21fc8c22 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_roles_{role_name}/put.js @@ -0,0 +1,4 @@ +await scalekit.role.updateRole("admin", { + displayName: "Admin (Updated)", + description: "Updated description" +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_roles_{role_name}_dependents/get.js b/openapi/code_samples/javascript/api_v1_roles_{role_name}_dependents/get.js new file mode 100644 index 000000000..f36221645 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_roles_{role_name}_dependents/get.js @@ -0,0 +1 @@ +const res = await scalekit.role.listDependentRoles("admin"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_roles_{role_name}_permissions/get.js b/openapi/code_samples/javascript/api_v1_roles_{role_name}_permissions/get.js new file mode 100644 index 000000000..b75c9e0e7 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_roles_{role_name}_permissions/get.js @@ -0,0 +1 @@ +const res = await scalekit.permission.listRolePermissions("admin"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_roles_{role_name}_permissions/post.js b/openapi/code_samples/javascript/api_v1_roles_{role_name}_permissions/post.js new file mode 100644 index 000000000..360c2159f --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_roles_{role_name}_permissions/post.js @@ -0,0 +1 @@ +await scalekit.permission.addPermissionsToRole("role_admin", ["perm.read", "perm.write"]); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_roles_{role_name}_permissions_{permission_name}/delete.js b/openapi/code_samples/javascript/api_v1_roles_{role_name}_permissions_{permission_name}/delete.js new file mode 100644 index 000000000..f3e45bf90 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_roles_{role_name}_permissions_{permission_name}/delete.js @@ -0,0 +1 @@ +await scalekit.permission.removePermissionFromRole("admin", "read:users"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_roles_{role_name}_users:count/get.js b/openapi/code_samples/javascript/api_v1_roles_{role_name}_users:count/get.js new file mode 100644 index 000000000..4ad8ad596 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_roles_{role_name}_users:count/get.js @@ -0,0 +1 @@ +const res = await scalekit.role.getRoleUsersCount("admin"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_sessions_{session_id}/get.js b/openapi/code_samples/javascript/api_v1_sessions_{session_id}/get.js new file mode 100644 index 000000000..fe7cb5c0d --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_sessions_{session_id}/get.js @@ -0,0 +1 @@ +const res = await scalekit.session.getSession("ses_123456789"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_sessions_{session_id}_revoke/post.js b/openapi/code_samples/javascript/api_v1_sessions_{session_id}_revoke/post.js new file mode 100644 index 000000000..ac910fa01 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_sessions_{session_id}_revoke/post.js @@ -0,0 +1 @@ +const res = await scalekit.session.revokeSession("ses_123456789"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_users/get.js b/openapi/code_samples/javascript/api_v1_users/get.js new file mode 100644 index 000000000..3b7b9bc7f --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_users/get.js @@ -0,0 +1,2 @@ +const response = await scalekit.user.listUsers( + { pageSize: 100 }); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_users_{id}/delete.js b/openapi/code_samples/javascript/api_v1_users_{id}/delete.js new file mode 100644 index 000000000..47827b71d --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_users_{id}/delete.js @@ -0,0 +1 @@ +await scalekit.user.deleteUser("usr_123"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_users_{id}/get.js b/openapi/code_samples/javascript/api_v1_users_{id}/get.js new file mode 100644 index 000000000..3d817f27c --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_users_{id}/get.js @@ -0,0 +1 @@ +const { user } = await scalekit.user.getUser("usr_123456"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_users_{id}/patch.js b/openapi/code_samples/javascript/api_v1_users_{id}/patch.js new file mode 100644 index 000000000..b0961523a --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_users_{id}/patch.js @@ -0,0 +1,9 @@ +await scalekit.user.updateUser("usr_123", { + userProfile: { + firstName: "John", + lastName: "Smith", + }, + metadata: { + department: "sales", + }, +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_users_{user_id}_sessions/get.js b/openapi/code_samples/javascript/api_v1_users_{user_id}_sessions/get.js new file mode 100644 index 000000000..68f7b2fb5 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_users_{user_id}_sessions/get.js @@ -0,0 +1,13 @@ +// Basic usage +const res = await scalekit.session.getUserSessions("user_123"); + +// With pagination and filtering +const res = await scalekit.session.getUserSessions("user_123", { + pageSize: 10, + pageToken: "next_page_token", + filter: { + status: ["ACTIVE"], + startTime: new Date("2024-01-01"), + endTime: new Date("2024-12-31") + } +}); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_users_{user_id}_sessions_revoke/post.js b/openapi/code_samples/javascript/api_v1_users_{user_id}_sessions_revoke/post.js new file mode 100644 index 000000000..df6e80d6b --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_users_{user_id}_sessions_revoke/post.js @@ -0,0 +1 @@ +const res = await scalekit.session.revokeAllUserSessions("user_123"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_webauthn_credentials/get.js b/openapi/code_samples/javascript/api_v1_webauthn_credentials/get.js new file mode 100644 index 000000000..12d2e9e53 --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_webauthn_credentials/get.js @@ -0,0 +1 @@ +const res = await scalekit.webauthn.listCredentials("user_123"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_webauthn_credentials_{credential_id}/delete.js b/openapi/code_samples/javascript/api_v1_webauthn_credentials_{credential_id}/delete.js new file mode 100644 index 000000000..8318726dd --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_webauthn_credentials_{credential_id}/delete.js @@ -0,0 +1 @@ +const res = await scalekit.webauthn.deleteCredential("wac_123"); \ No newline at end of file diff --git a/openapi/code_samples/javascript/api_v1_webauthn_credentials_{credential_id}/patch.js b/openapi/code_samples/javascript/api_v1_webauthn_credentials_{credential_id}/patch.js new file mode 100644 index 000000000..daa03e55e --- /dev/null +++ b/openapi/code_samples/javascript/api_v1_webauthn_credentials_{credential_id}/patch.js @@ -0,0 +1,4 @@ +const res = await scalekit.webauthn.updateCredential( + "wac_123", + "Work Laptop Passkey" +); \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_connections/get.py b/openapi/code_samples/python/api_v1_connections/get.py new file mode 100644 index 000000000..62533de66 --- /dev/null +++ b/openapi/code_samples/python/api_v1_connections/get.py @@ -0,0 +1,7 @@ +# List connections by organization id +connections = scalekit_client.connection.list_connections( + organization_id +) + +# List connections by domain +response = scalekit_client.connection.list_connections_by_domain(domain="example.com") \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_memberships_organizations_{organization_id}_users_{id}/delete.py b/openapi/code_samples/python/api_v1_memberships_organizations_{organization_id}_users_{id}/delete.py new file mode 100644 index 000000000..2a6f7b3cd --- /dev/null +++ b/openapi/code_samples/python/api_v1_memberships_organizations_{organization_id}_users_{id}/delete.py @@ -0,0 +1,3 @@ +response = scalekit_client.users.delete_membership( + organization_id=org_id,user_id=user_id +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_memberships_organizations_{organization_id}_users_{id}/post.py b/openapi/code_samples/python/api_v1_memberships_organizations_{organization_id}_users_{id}/post.py new file mode 100644 index 000000000..ddff07773 --- /dev/null +++ b/openapi/code_samples/python/api_v1_memberships_organizations_{organization_id}_users_{id}/post.py @@ -0,0 +1,12 @@ +from scalekit.v1.users.users_pb2 import CreateMembership +from scalekit.v1.commons.commons_pb2 import Role + +membership = CreateMembership( + roles=[Role(name="admin")], + metadata={"department": "engineering", "location": "nyc-office"}, +) +resp = scalekit_client.users.create_membership( + organization_id="org_123", + user_id="usr_123", + membership=membership, +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations/get.py b/openapi/code_samples/python/api_v1_organizations/get.py new file mode 100644 index 000000000..63baa6c48 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations/get.py @@ -0,0 +1,6 @@ +options = ListOrganizationOptions() +options.page_size = 10 + +organizations = scalekit_client.organization.list_organizations( + options=options +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations/post.py b/openapi/code_samples/python/api_v1_organizations/post.py new file mode 100644 index 000000000..e833017b5 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations/post.py @@ -0,0 +1,6 @@ +options = CreateOrganizationOptions() +options.external_id = "externalId" +organization = scalekit_client.organization.create_organization( + name, + options=options +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{id}/delete.py b/openapi/code_samples/python/api_v1_organizations_{id}/delete.py new file mode 100644 index 000000000..5d71d58f1 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{id}/delete.py @@ -0,0 +1 @@ +scalekit_client.organization.delete_organization(organization_id) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{id}/get.py b/openapi/code_samples/python/api_v1_organizations_{id}/get.py new file mode 100644 index 000000000..b7bd8f4ef --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{id}/get.py @@ -0,0 +1,9 @@ +scalekit_client = ScalekitClient( + , + , + +) + +organization = scalekit_client.organization.get_organization( + organization_id +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{id}/patch.py b/openapi/code_samples/python/api_v1_organizations_{id}/patch.py new file mode 100644 index 000000000..4fe3eba6b --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{id}/patch.py @@ -0,0 +1,4 @@ +organization = scalekit_client.organization.update_organization(organization_id, { + display_name: "display_name", + external_id: "external_id" +}) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{id}_portal_links/put.py b/openapi/code_samples/python/api_v1_organizations_{id}_portal_links/put.py new file mode 100644 index 000000000..d5ceae6e8 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{id}_portal_links/put.py @@ -0,0 +1,3 @@ +link = scalekit_client.organization.generate_portal_link( + organization_id +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{id}_settings/patch.py b/openapi/code_samples/python/api_v1_organizations_{id}_settings/patch.py new file mode 100644 index 000000000..4273b7d88 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{id}_settings/patch.py @@ -0,0 +1,14 @@ +settings = [ + { + "name": "sso", + "enabled": True + }, + { + "name": "dir_sync", + "enabled": True + } + ] + +scalekit_client.organization.update_organization_settings( + organization_id='', settings=settings +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{org_id}_roles/get.py b/openapi/code_samples/python/api_v1_organizations_{org_id}_roles/get.py new file mode 100644 index 000000000..3897b1768 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{org_id}_roles/get.py @@ -0,0 +1 @@ +res = scalekit_client.roles.list_organization_roles(org_id="org_123") \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{org_id}_roles/post.py b/openapi/code_samples/python/api_v1_organizations_{org_id}_roles/post.py new file mode 100644 index 000000000..7f7adbd1e --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{org_id}_roles/post.py @@ -0,0 +1,14 @@ +from scalekit.v1.roles.roles_pb2 import CreateOrganizationRole + +role = CreateOrganizationRole( + name="org_admin", + display_name="Org Admin", + description="Organization-scoped role", + extends="base_role_name", # optional + permissions=["perm.read", "perm.write"] # optional +) + +scalekit_client.roles.create_organization_role( + org_id="org_123", + role=role +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{org_id}_roles:set_defaults/patch.py b/openapi/code_samples/python/api_v1_organizations_{org_id}_roles:set_defaults/patch.py new file mode 100644 index 000000000..0c3d3c21c --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{org_id}_roles:set_defaults/patch.py @@ -0,0 +1,8 @@ +from scalekit.v1.roles.roles_pb2 import UpdateDefaultOrganizationRolesRequest + +res = scalekit_client.roles.update_default_organization_roles( + org_id="org_123", + default_roles=UpdateDefaultOrganizationRolesRequest( + default_member_role="org_member" + ) +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{org_id}_roles_{role_name}/delete.py b/openapi/code_samples/python/api_v1_organizations_{org_id}_roles_{role_name}/delete.py new file mode 100644 index 000000000..af2a74c15 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{org_id}_roles_{role_name}/delete.py @@ -0,0 +1,12 @@ +# Basic delete +scalekit_client.roles.delete_organization_role( + org_id="org_123", + role_name="org_role_admin" +) + +# With reassignment +scalekit_client.roles.delete_organization_role( + org_id="org_123", + role_name="org_role_admin", + reassign_role_name="org_role_member" +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{org_id}_roles_{role_name}/get.py b/openapi/code_samples/python/api_v1_organizations_{org_id}_roles_{role_name}/get.py new file mode 100644 index 000000000..c718f0c37 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{org_id}_roles_{role_name}/get.py @@ -0,0 +1,4 @@ +res = scalekit_client.roles.get_organization_role( + org_id="org_123", + role_name="org_admin" +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{org_id}_roles_{role_name}/put.py b/openapi/code_samples/python/api_v1_organizations_{org_id}_roles_{role_name}/put.py new file mode 100644 index 000000000..92c37d7a3 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{org_id}_roles_{role_name}/put.py @@ -0,0 +1,10 @@ +from scalekit.v1.roles.roles_pb2 import UpdateRole + +scalekit_client.roles.update_organization_role( + org_id="org_123", + role_name="org_admin", + role=UpdateRole( + display_name="Org Admin (Updated)", + description="Updated org role description" + ) +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients/get.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients/get.py new file mode 100644 index 000000000..c7352c75d --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients/get.py @@ -0,0 +1,13 @@ +# List clients for a specific organization +org_id = 'SCALEKIT_ORGANIZATION_ID' + +# Retrieve all clients with default pagination +response = scalekit_client.m2m_client.list_organization_clients( + organization_id=org_id, + page_size=30 +) + +# Access the clients list +clients = response.clients +for client in clients: + print(f"Client ID: {scalekit_client.id}, Name: {scalekit_client.name}") \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients/post.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients/post.py new file mode 100644 index 000000000..0c9340e17 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients/post.py @@ -0,0 +1,19 @@ +from scalekit.v1.clients.clients_pb2 import OrganizationClient + +m2m_client = OrganizationClient( + name="GitHub Actions Deployment Service", + description="Service account for GitHub Actions to deploy applications +to production", + custom_claims=[ + {"key": "github_repository", "value": "acmecorp/inventory-service"}, + {"key": "environment", "value": "production_us"} + ], + scopes=["deploy:applications", "read:deployments"], + audience=["deployment-api.acmecorp.com"], + expiry=3600 +) + +response = scalekit_client.m2m_client.create_organization_client( + organization_id="SCALEKIT_ORGANIZATION_ID", + m2m_client=m2m_client +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}/delete.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}/delete.py new file mode 100644 index 000000000..fc0c56789 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}/delete.py @@ -0,0 +1,9 @@ +# Get client ID from environment variables +org_id = '' +client_id = os.environ['M2M_CLIENT_ID'] + +# Delete the specified client from the organization +response = scalekit_client.m2m_client.delete_organization_client( + organization_id=org_id, + client_id=client_id +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}/get.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}/get.py new file mode 100644 index 000000000..a4d98c22a --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}/get.py @@ -0,0 +1,9 @@ +# Get client ID from environment variables +org_id = 'SCALEKIT_ORGANIZATION_ID' +client_id = os.environ['M2M_CLIENT_ID'] + +# Fetch client details for the specified organization +response = scalekit_client.m2m_client.get_organization_client( + organization_id=org_id, + client_id=client_id +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}/patch.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}/patch.py new file mode 100644 index 000000000..bdf59e892 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}/patch.py @@ -0,0 +1,19 @@ +from scalekit.v1.clients.clients_pb2 import OrganizationClient + +org_id = '' +client_id = os.environ['M2M_CLIENT_ID'] + +update_m2m_client = OrganizationClient( + description="Service account for GitHub Actions to deploy applications +to production_eu", + custom_claims=[ + {"key": "github_repository", "value": "acmecorp/inventory"}, + {"key": "environment", "value": "production_eu"} + ] +) + +response = scalekit_client.m2m_client.update_organization_client( + organization_id=org_id, + client_id=client_id, + m2m_client=update_m2m_client +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}_secrets/post.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}_secrets/post.py new file mode 100644 index 000000000..6c6ad6b5e --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}_secrets/post.py @@ -0,0 +1,12 @@ +# Get client ID from environment variables +org_id = 'SCALEKIT_ORGANIZATION_ID' +client_id = os.environ['M2M_CLIENT_ID'] + +# Add a new secret to the specified client +response = scalekit_client.m2m_client.add_organization_client_secret( + organization_id=org_id, + client_id=client_id +) + +# Extract the secret ID from the response +secret_id = response[0].secret.id \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}_secrets_{secret_id}/delete.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}_secrets_{secret_id}/delete.py new file mode 100644 index 000000000..e71ff7b07 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}_secrets_{secret_id}/delete.py @@ -0,0 +1,11 @@ +# Get client and secret IDs from environment variables +org_id = '' +client_id = os.environ['M2M_CLIENT_ID'] +secret_id = os.environ['M2M_SECRET_ID'] + +# Remove the specified secret from the client +response = scalekit_client.m2m_client.remove_organization_client_secret( + organization_id=org_id, + client_id=client_id, + secret_id=secret_id +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_connections_{id}/delete.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_connections_{id}/delete.py new file mode 100644 index 000000000..1e1a010ff --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_connections_{id}/delete.py @@ -0,0 +1,4 @@ +scalekit_client.connection.delete_connection( + organization_id, + connection_id +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_connections_{id}/get.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_connections_{id}/get.py new file mode 100644 index 000000000..92e430c60 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_connections_{id}/get.py @@ -0,0 +1,4 @@ +connection = scalekit_client.connection.get_connection( + organization_id, + connection_id, +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.py new file mode 100644 index 000000000..eb79d14b7 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.py @@ -0,0 +1,4 @@ +scalekit_client.connection.disable_connection( + organization_id, + connection_id +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.py new file mode 100644 index 000000000..3cded2a14 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.py @@ -0,0 +1,4 @@ +scalekit_client.connection.enable_connection( + organization_id, + connection_id, +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories/get.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories/get.py new file mode 100644 index 000000000..474c2fa5d --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories/get.py @@ -0,0 +1,3 @@ +directories_list = scalekit_client.directory.list_directories( + organization_id='' +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.py new file mode 100644 index 000000000..132671a55 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.py @@ -0,0 +1,3 @@ +directory_groups = scalekit_client.directory.list_directory_groups( + directory_id='', organization_id='' +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.py new file mode 100644 index 000000000..2923ac017 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.py @@ -0,0 +1,3 @@ +directory_users = scalekit_client.directory.list_directory_users( + directory_id='', organization_id='' +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories_{id}/get.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories_{id}/get.py new file mode 100644 index 000000000..3a483542e --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories_{id}/get.py @@ -0,0 +1,4 @@ +directory = scalekit_client.directory.get_directory( + directory_id='', organization_id='' +) +print(f'Directory details: {directory}') \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.py new file mode 100644 index 000000000..18b322697 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.py @@ -0,0 +1,3 @@ +directory_response = scalekit_client.directory.disable_directory( + directory_id='', organization_id='' +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.py new file mode 100644 index 000000000..712b47e1f --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.py @@ -0,0 +1,3 @@ +directory_response = scalekit_client.directory.enable_directory( + directory_id='', organization_id='' +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_domains/get.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_domains/get.py new file mode 100644 index 000000000..edd0cfddc --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_domains/get.py @@ -0,0 +1,7 @@ +# List all domains in an organization +response = scalekit_client.domain.list_domains( + organization_id="org_123", + domain_type="ORGANIZATION_DOMAIN" + ) +# - organization_id: Owning organization +# - domain_type: domain type \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_domains/post.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_domains/post.py new file mode 100644 index 000000000..b873f4032 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_domains/post.py @@ -0,0 +1,5 @@ +# Add a new domain to an organization +response = scalekit_client.domain.create_domain(organization_id="org-123", + + domain_name="example.com", + domain_type="ORGANIZATION_DOMAIN") \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_domains_{id}/delete.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_domains_{id}/delete.py new file mode 100644 index 000000000..35a247be1 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_domains_{id}/delete.py @@ -0,0 +1,6 @@ +# Remove a domain from an organization +# Caution: Deletion is permanent and may affect user access +response = scalekit_client.domain.delete_domain( + organization_id="org_123", + domain_id="dom_123" +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_domains_{id}/get.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_domains_{id}/get.py new file mode 100644 index 000000000..e16f55327 --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_domains_{id}/get.py @@ -0,0 +1,2 @@ +# Fetch details of a specific domain +response = scalekit_client.domain.get_domain(organization_id="org_123", domain_id="dom_123") \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_users/get.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_users/get.py new file mode 100644 index 000000000..390eac78e --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_users/get.py @@ -0,0 +1 @@ +resp, _ = scalekit_client.users.list_users(organization_id="org_123", page_size=50) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_users/post.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_users/post.py new file mode 100644 index 000000000..0e33d31ac --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_users/post.py @@ -0,0 +1,24 @@ +# Create user with membership +user = CreateUser( + email="john.doe@example.com", + external_id="ext_john_123", # Optional + user_profile={ + "first_name": "John", + "last_name": "Doe", + "name": "John Doe", + "locale": "en-US", + "phone_number": "+14155552671" + }, + membership={ + "roles": [{"name": "member"}] + } +) + +# Create user and membership in organization +response = scalekit_client.users.create_user_and_membership( + organization_id="your_org_id", + user=user, + send_invitation_email=True # Set to False if you don't want to send +email ) + + user_id = response[0].user.id \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.py new file mode 100644 index 000000000..433968c3b --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.py @@ -0,0 +1,5 @@ +resp = scalekit_client.users.list_user_permissions( + organization_id="org_123", + user_id="usr_123", +) +permissions = resp.permissions \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.py b/openapi/code_samples/python/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.py new file mode 100644 index 000000000..c4bff419f --- /dev/null +++ b/openapi/code_samples/python/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.py @@ -0,0 +1,5 @@ +resp = scalekit_client.users.list_user_roles( + organization_id="org_123", + user_id="usr_123", +) +roles = resp.roles \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_passwordless_email_resend/post.py b/openapi/code_samples/python/api_v1_passwordless_email_resend/post.py new file mode 100644 index 000000000..381bd292a --- /dev/null +++ b/openapi/code_samples/python/api_v1_passwordless_email_resend/post.py @@ -0,0 +1,6 @@ +resend_response = scalekit_client.passwordless.resend_passwordless_email( + auth_request_id=auth_request_id, +) + +# New auth request ID from resend +new_auth_request_id = resend_response[0].auth_request_id \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_passwordless_email_send/post.py b/openapi/code_samples/python/api_v1_passwordless_email_send/post.py new file mode 100644 index 000000000..9a0f3f37b --- /dev/null +++ b/openapi/code_samples/python/api_v1_passwordless_email_send/post.py @@ -0,0 +1,14 @@ +response = scalekit_client.passwordless.send_passwordless_email( + email="john.doe@example.com", + template="SIGNIN", # or "SIGNUP", "UNSPECIFIED" + expires_in=100, + magiclink_auth_uri="https://www.google.com", + template_variables={ + "employeeID": "EMP523", + "teamName": "Alpha Team", + "supportEmail": "support@yourcompany.com", + }, +) + +# Extract auth request ID from response +auth_request_id = response[0].auth_request_id \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_passwordless_email_verify/post.py b/openapi/code_samples/python/api_v1_passwordless_email_verify/post.py new file mode 100644 index 000000000..68f441903 --- /dev/null +++ b/openapi/code_samples/python/api_v1_passwordless_email_verify/post.py @@ -0,0 +1,13 @@ +# Verify with OTP code +verify_response = scalekit_client.passwordless.verify_passwordless_email( + code="123456", # OTP code received via email + auth_request_id=auth_request_id, +) + +# Verify with magic link token +verify_response = scalekit_client.passwordless.verify_passwordless_email( + link_token=link_token, # Magic link token from URL +) + +# User verified successfully +user_email = verify_response[0].email \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_permissions/get.py b/openapi/code_samples/python/api_v1_permissions/get.py new file mode 100644 index 000000000..0239ef847 --- /dev/null +++ b/openapi/code_samples/python/api_v1_permissions/get.py @@ -0,0 +1 @@ +res = scalekit_client.permissions.list_permissions() \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_permissions/post.py b/openapi/code_samples/python/api_v1_permissions/post.py new file mode 100644 index 000000000..f2a97c739 --- /dev/null +++ b/openapi/code_samples/python/api_v1_permissions/post.py @@ -0,0 +1,8 @@ +from scalekit.v1.roles.roles_pb2 import CreatePermission + +permission = CreatePermission( + name="read:users", + description="Allows reading users" +) + +scalekit_client.permissions.create_permission(permission=permission) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_permissions_{permission_name}/delete.py b/openapi/code_samples/python/api_v1_permissions_{permission_name}/delete.py new file mode 100644 index 000000000..77060a854 --- /dev/null +++ b/openapi/code_samples/python/api_v1_permissions_{permission_name}/delete.py @@ -0,0 +1,3 @@ +scalekit_client.permissions.delete_permission( + permission_name="read:users" +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_permissions_{permission_name}/get.py b/openapi/code_samples/python/api_v1_permissions_{permission_name}/get.py new file mode 100644 index 000000000..12df2b2c9 --- /dev/null +++ b/openapi/code_samples/python/api_v1_permissions_{permission_name}/get.py @@ -0,0 +1,3 @@ +res = scalekit_client.permissions.get_permission( + permission_name="read:users" +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_permissions_{permission_name}/put.py b/openapi/code_samples/python/api_v1_permissions_{permission_name}/put.py new file mode 100644 index 000000000..7bdddb646 --- /dev/null +++ b/openapi/code_samples/python/api_v1_permissions_{permission_name}/put.py @@ -0,0 +1,9 @@ +from scalekit.v1.roles.roles_pb2 import CreatePermission + +scalekit_client.permissions.update_permission( + permission_name="read:users", + permission=CreatePermission( + name="read:users", + description="Allows reading user resources" + ) +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_roles/get.py b/openapi/code_samples/python/api_v1_roles/get.py new file mode 100644 index 000000000..a5d05ce53 --- /dev/null +++ b/openapi/code_samples/python/api_v1_roles/get.py @@ -0,0 +1 @@ +res = scalekit_client.roles.list_roles() \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_roles/post.py b/openapi/code_samples/python/api_v1_roles/post.py new file mode 100644 index 000000000..fb48fbe59 --- /dev/null +++ b/openapi/code_samples/python/api_v1_roles/post.py @@ -0,0 +1,11 @@ +from scalekit.v1.roles.roles_pb2 import CreateRole + +role = CreateRole( + name="admin", + display_name="Admin", + description="Environment-level role", + extends="base_role", # optional + permissions=["read:users"] # optional +) + +scalekit_client.roles.create_role(role=role) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_roles:set_defaults/patch.py b/openapi/code_samples/python/api_v1_roles:set_defaults/patch.py new file mode 100644 index 000000000..2cd6b8f54 --- /dev/null +++ b/openapi/code_samples/python/api_v1_roles:set_defaults/patch.py @@ -0,0 +1,7 @@ +from scalekit.v1.roles.roles_pb2 import UpdateDefaultRolesRequest + +res = scalekit_client.roles.update_default_roles( + default_roles=UpdateDefaultRolesRequest( + default_member_role="member" + ) +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_roles_{role_name}/delete.py b/openapi/code_samples/python/api_v1_roles_{role_name}/delete.py new file mode 100644 index 000000000..d6f024a42 --- /dev/null +++ b/openapi/code_samples/python/api_v1_roles_{role_name}/delete.py @@ -0,0 +1,8 @@ +# Basic delete +scalekit_client.roles.delete_role(role_name="admin") + +# With reassignment +scalekit_client.roles.delete_role( + role_name="admin", + reassign_role_name="member" +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_roles_{role_name}/get.py b/openapi/code_samples/python/api_v1_roles_{role_name}/get.py new file mode 100644 index 000000000..d44fa2bda --- /dev/null +++ b/openapi/code_samples/python/api_v1_roles_{role_name}/get.py @@ -0,0 +1 @@ +res = scalekit_client.roles.get_role(role_name="admin") \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_roles_{role_name}/put.py b/openapi/code_samples/python/api_v1_roles_{role_name}/put.py new file mode 100644 index 000000000..9a957b3d9 --- /dev/null +++ b/openapi/code_samples/python/api_v1_roles_{role_name}/put.py @@ -0,0 +1,9 @@ +from scalekit.v1.roles.roles_pb2 import UpdateRole + +scalekit_client.roles.update_role( + role_name="admin", + role=UpdateRole( + display_name="Admin (Updated)", + description="Updated description" + ) +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_roles_{role_name}_dependents/get.py b/openapi/code_samples/python/api_v1_roles_{role_name}_dependents/get.py new file mode 100644 index 000000000..663272c01 --- /dev/null +++ b/openapi/code_samples/python/api_v1_roles_{role_name}_dependents/get.py @@ -0,0 +1 @@ +res = scalekit_client.roles.list_dependent_roles(role_name="admin") \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_roles_{role_name}_permissions/get.py b/openapi/code_samples/python/api_v1_roles_{role_name}_permissions/get.py new file mode 100644 index 000000000..8e3bb1df0 --- /dev/null +++ b/openapi/code_samples/python/api_v1_roles_{role_name}_permissions/get.py @@ -0,0 +1 @@ +res = scalekit_client.permissions.list_role_permissions(role_name="admin") \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_roles_{role_name}_permissions/post.py b/openapi/code_samples/python/api_v1_roles_{role_name}_permissions/post.py new file mode 100644 index 000000000..cd39902d9 --- /dev/null +++ b/openapi/code_samples/python/api_v1_roles_{role_name}_permissions/post.py @@ -0,0 +1,4 @@ +scalekit_client.permissions.add_permissions_to_role( + role_name="role_admin", + permission_names=["perm.read", "perm.write"] +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_roles_{role_name}_permissions_{permission_name}/delete.py b/openapi/code_samples/python/api_v1_roles_{role_name}_permissions_{permission_name}/delete.py new file mode 100644 index 000000000..0aaa3809e --- /dev/null +++ b/openapi/code_samples/python/api_v1_roles_{role_name}_permissions_{permission_name}/delete.py @@ -0,0 +1,4 @@ +scalekit_client.permissions.remove_permission_from_role( + role_name="admin", + permission_name="read:users" +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_roles_{role_name}_users:count/get.py b/openapi/code_samples/python/api_v1_roles_{role_name}_users:count/get.py new file mode 100644 index 000000000..47d69b7dc --- /dev/null +++ b/openapi/code_samples/python/api_v1_roles_{role_name}_users:count/get.py @@ -0,0 +1 @@ +res = scalekit_client.roles.get_role_users_count(role_name="admin") \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_sessions_{session_id}/get.py b/openapi/code_samples/python/api_v1_sessions_{session_id}/get.py new file mode 100644 index 000000000..defe66a4f --- /dev/null +++ b/openapi/code_samples/python/api_v1_sessions_{session_id}/get.py @@ -0,0 +1 @@ +res = scalekit_client.sessions.get_session(session_id="ses_123456789") \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_sessions_{session_id}_revoke/post.py b/openapi/code_samples/python/api_v1_sessions_{session_id}_revoke/post.py new file mode 100644 index 000000000..c6fcf67de --- /dev/null +++ b/openapi/code_samples/python/api_v1_sessions_{session_id}_revoke/post.py @@ -0,0 +1 @@ +res = scalekit_client.sessions.revoke_session(session_id="ses_123456789") \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_users/get.py b/openapi/code_samples/python/api_v1_users/get.py new file mode 100644 index 000000000..4af01957e --- /dev/null +++ b/openapi/code_samples/python/api_v1_users/get.py @@ -0,0 +1,2 @@ +# pass empty org to fetch all users in environment +resp,_ = scalekit_client.users.list_users(organization_id="", page_size=100) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_users_{id}/delete.py b/openapi/code_samples/python/api_v1_users_{id}/delete.py new file mode 100644 index 000000000..5376746d5 --- /dev/null +++ b/openapi/code_samples/python/api_v1_users_{id}/delete.py @@ -0,0 +1,2 @@ +scalekit_client.users.delete_user(organization_id="org_123", + user_id="usr_123") \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_users_{id}/get.py b/openapi/code_samples/python/api_v1_users_{id}/get.py new file mode 100644 index 000000000..71f77a0e2 --- /dev/null +++ b/openapi/code_samples/python/api_v1_users_{id}/get.py @@ -0,0 +1,2 @@ +resp = scalekit_client.users.get_user(user_id="usr_123456") +user = resp.user \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_users_{id}/patch.py b/openapi/code_samples/python/api_v1_users_{id}/patch.py new file mode 100644 index 000000000..17c4835b6 --- /dev/null +++ b/openapi/code_samples/python/api_v1_users_{id}/patch.py @@ -0,0 +1,18 @@ +import os +from scalekit import ScalekitClient +from scalekit.v1.users.users_pb2 import UpdateUser +from scalekit.v1.commons.commons_pb2 import UserProfile +scalekit_client = ScalekitClient( + env_url=os.getenv("SCALEKIT_ENV_URL"), + client_id=os.getenv("SCALEKIT_CLIENT_ID"), + client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"), +) +update_user = UpdateUser( + user_profile=UserProfile( + first_name="John", + last_name="Smith" + ), + metadata={"department": "sales"} +) +scalekit_client.users.update_user(organization_id="org_123", + user=update_user) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_users_{user_id}_sessions/get.py b/openapi/code_samples/python/api_v1_users_{user_id}_sessions/get.py new file mode 100644 index 000000000..360b23eaa --- /dev/null +++ b/openapi/code_samples/python/api_v1_users_{user_id}_sessions/get.py @@ -0,0 +1,18 @@ +# Basic usage +res = scalekit_client.sessions.get_user_sessions(user_id="user_123") + +# With pagination and filtering +from google.protobuf.timestamp_pb2 import Timestamp +from datetime import datetime + +start_time = Timestamp() +start_time.FromDatetime(datetime(2024, 1, 1)) +end_time = Timestamp() +end_time.FromDatetime(datetime(2024, 12, 31)) + +filter_obj = scalekit_client.sessions.create_session_filter( + status=["ACTIVE"], start_time=start_time, end_time=end_time +) +res = scalekit_client.sessions.get_user_sessions( + user_id="user_123", page_size=10, page_token="next_page_token", filter=filter_obj +) \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_users_{user_id}_sessions_revoke/post.py b/openapi/code_samples/python/api_v1_users_{user_id}_sessions_revoke/post.py new file mode 100644 index 000000000..7028f0ebb --- /dev/null +++ b/openapi/code_samples/python/api_v1_users_{user_id}_sessions_revoke/post.py @@ -0,0 +1 @@ +res = scalekit_client.sessions.revoke_all_user_sessions(user_id="user_123") \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_webauthn_credentials/get.py b/openapi/code_samples/python/api_v1_webauthn_credentials/get.py new file mode 100644 index 000000000..98e263f89 --- /dev/null +++ b/openapi/code_samples/python/api_v1_webauthn_credentials/get.py @@ -0,0 +1 @@ +res = scalekit_client.webauthn.list_credentials(user_id="user_123") \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_webauthn_credentials_{credential_id}/delete.py b/openapi/code_samples/python/api_v1_webauthn_credentials_{credential_id}/delete.py new file mode 100644 index 000000000..891299b2f --- /dev/null +++ b/openapi/code_samples/python/api_v1_webauthn_credentials_{credential_id}/delete.py @@ -0,0 +1 @@ +res = scalekit_client.webauthn.delete_credential(credential_id="wac_123") \ No newline at end of file diff --git a/openapi/code_samples/python/api_v1_webauthn_credentials_{credential_id}/patch.py b/openapi/code_samples/python/api_v1_webauthn_credentials_{credential_id}/patch.py new file mode 100644 index 000000000..48c3e0602 --- /dev/null +++ b/openapi/code_samples/python/api_v1_webauthn_credentials_{credential_id}/patch.py @@ -0,0 +1,4 @@ +res = scalekit_client.webauthn.update_credential( + credential_id="wac_123", + display_name="Work Laptop Passkey" +) \ No newline at end of file diff --git a/openapi/components/schemas/HelpInfoLink.yaml b/openapi/components/schemas/HelpInfoLink.yaml new file mode 100644 index 000000000..ac17654f3 --- /dev/null +++ b/openapi/components/schemas/HelpInfoLink.yaml @@ -0,0 +1,11 @@ +description: A documentation or reference link. +type: object +properties: + description: + description: Human-readable label for the link (e.g. "User verification flow"). + type: string + url: + description: >- + Absolute URL to the documentation page (e.g. + "https://docs.scalekit.com/..."). + type: string diff --git a/openapi/components/schemas/OrganizationServiceUpdateOrganizationSessionPolicyBody.yaml b/openapi/components/schemas/OrganizationServiceUpdateOrganizationSessionPolicyBody.yaml new file mode 100644 index 000000000..1a01d0d65 --- /dev/null +++ b/openapi/components/schemas/OrganizationServiceUpdateOrganizationSessionPolicyBody.yaml @@ -0,0 +1,47 @@ +type: object +properties: + absolute_session_timeout: + description: >- + The absolute session timeout value. The unit is specified by + absolute_session_timeout_unit. Omit when policy_source is APPLICATION. + type: integer + format: int32 + examples: + - 360 + absolute_session_timeout_unit: + description: >- + Unit for absolute_session_timeout. Accepted values: 'MINUTES', 'HOURS', + 'DAYS'. Defaults to MINUTES. + $ref: ./commonsTimeUnit.yaml + examples: + - MINUTES + idle_session_timeout: + description: >- + The idle session timeout value. The unit is specified by + idle_session_timeout_unit. Omit when idle_session_timeout_enabled is + false. + type: integer + format: int32 + examples: + - 84 + idle_session_timeout_enabled: + description: >- + Whether idle session timeout is enabled. Omit when policy_source is + APPLICATION. + type: boolean + examples: + - true + idle_session_timeout_unit: + description: >- + Unit for idle_session_timeout. Accepted values: 'MINUTES', 'HOURS', + 'DAYS'. Defaults to MINUTES. + $ref: ./commonsTimeUnit.yaml + examples: + - MINUTES + policy_source: + description: >- + Policy source. Send 'APPLICATION' to revert to application defaults. Send + 'CUSTOM' with timeout values to activate a custom policy. + $ref: ./organizationsSessionPolicyType.yaml + examples: + - CUSTOM diff --git a/openapi/components/schemas/OrganizationServiceUpsertUserManagementSettingsBody.yaml b/openapi/components/schemas/OrganizationServiceUpsertUserManagementSettingsBody.yaml new file mode 100644 index 000000000..3d9ecc708 --- /dev/null +++ b/openapi/components/schemas/OrganizationServiceUpsertUserManagementSettingsBody.yaml @@ -0,0 +1,5 @@ +type: object +properties: + settings: + description: The new values for the setting fields to patch. + $ref: ./organizationsOrganizationUserManagementSettings.yaml diff --git a/openapi/components/schemas/RolesServiceAddPermissionsToRoleBody.yaml b/openapi/components/schemas/RolesServiceAddPermissionsToRoleBody.yaml new file mode 100644 index 000000000..66245ce74 --- /dev/null +++ b/openapi/components/schemas/RolesServiceAddPermissionsToRoleBody.yaml @@ -0,0 +1,7 @@ +type: object +properties: + permission_names: + description: List of permission names to add to the role + type: array + items: + type: string diff --git a/openapi/components/schemas/RolesServiceUpdateDefaultOrganizationRolesBody.yaml b/openapi/components/schemas/RolesServiceUpdateDefaultOrganizationRolesBody.yaml new file mode 100644 index 000000000..1f1133828 --- /dev/null +++ b/openapi/components/schemas/RolesServiceUpdateDefaultOrganizationRolesBody.yaml @@ -0,0 +1,7 @@ +type: object +properties: + default_member_role: + description: Unique name of the default member role + type: string + examples: + - member diff --git a/openapi/components/schemas/ScalekitEvent.yaml b/openapi/components/schemas/ScalekitEvent.yaml new file mode 100644 index 000000000..5a61c27cc --- /dev/null +++ b/openapi/components/schemas/ScalekitEvent.yaml @@ -0,0 +1,101 @@ +type: object +required: + - spec_version + - id + - type + - occurred_at + - environment_id + - object +properties: + spec_version: + type: string + example: '1' + description: The webhook specification version + pattern: ^[0-9]+$ + id: + type: string + pattern: ^evt_ + example: evt_1234567890abcdef + description: Unique identifier for the webhook event (must be prefixed with "evt_") + minLength: 1 + maxLength: 32 + type: + type: string + example: organization.created + description: The event type + enum: + - organization.created + - organization.updated + - organization.deleted + - organization.sso_created + - organization.sso_deleted + - organization.sso_enabled + - organization.sso_disabled + - user.signup + - user.login + - user.logout + - user.organization_invitation + - user.organization_membership_created + - user.organization_membership_updated + - user.organization_membership_deleted + - organization.directory.user_created + - organization.directory.user_updated + - organization.directory.user_deleted + - organization.directory.group_created + - organization.directory.group_updated + - organization.directory.group_deleted + - organization.directory_enabled + - organization.directory_disabled + - role.created + - role.updated + - role.deleted + - permission.created + - permission.updated + - permission.deleted + occurred_at: + type: string + format: date-time + description: When the event occurred (ISO 8601 format) + example: '2024-01-01T00:00:00Z' + environment_id: + type: string + pattern: ^env_ + example: env_1234567890abcdef + description: The environment ID where the event occurred + minLength: 1 + maxLength: 32 + organization_id: + type: string + pattern: ^org_ + example: org_1234567890abcdef + description: The organization ID (if applicable) + minLength: 1 + maxLength: 32 + object: + type: string + description: The type of object that triggered the webhook + enum: + - Organization + - Connection + - Role + - Directory + - DirectoryUser + - DirectoryGroup + - Permission + - OrgMembership + - User + example: Organization + data: + type: object + description: The event payload (structure varies by event type) + additionalProperties: true + example: + id: org_1234567890abcdef + name: Example Organization + created_at: '2024-01-01T00:00:00Z' + display_name: + type: string + description: Human-readable display name for the event + example: Organization Created + minLength: 1 + maxLength: 200 diff --git a/openapi/components/schemas/TestUser.yaml b/openapi/components/schemas/TestUser.yaml new file mode 100644 index 000000000..e28b3498c --- /dev/null +++ b/openapi/components/schemas/TestUser.yaml @@ -0,0 +1,27 @@ +type: object +properties: + enabled: + type: boolean + description: Whether test user mode is enabled for this environment. + example: true + emails: + type: array + items: + type: string + format: email + description: >- + Explicit list of test user email addresses. Each email must contain + '+sktest' in the local part (e.g. alice+sktest@example.com). Maximum 5 + emails per environment (configurable server-side). + example: + - alice+sktest@example.com + - bob+sktest@example.com + static_confirmation_code: + type: string + pattern: ^[0-9]{6}$ + minLength: 6 + maxLength: 6 + description: >- + Six-digit static OTP code used in place of a real verification email for + matched test users. + example: '424242' diff --git a/openapi/components/schemas/UserServiceResendInviteBody.yaml b/openapi/components/schemas/UserServiceResendInviteBody.yaml new file mode 100644 index 000000000..91bf3091f --- /dev/null +++ b/openapi/components/schemas/UserServiceResendInviteBody.yaml @@ -0,0 +1 @@ +type: object diff --git a/openapi/components/schemas/ValidationErrorInfoFieldViolation.yaml b/openapi/components/schemas/ValidationErrorInfoFieldViolation.yaml new file mode 100644 index 000000000..ee49b6cf2 --- /dev/null +++ b/openapi/components/schemas/ValidationErrorInfoFieldViolation.yaml @@ -0,0 +1,10 @@ +description: A message type used to describe a single bad request field. +type: object +properties: + constraint: + type: string + description: + description: A description of why the request element is bad. + type: string + field: + type: string diff --git a/openapi/components/schemas/WebAuthConfigurationAttestation.yaml b/openapi/components/schemas/WebAuthConfigurationAttestation.yaml new file mode 100644 index 000000000..aa87ef8ff --- /dev/null +++ b/openapi/components/schemas/WebAuthConfigurationAttestation.yaml @@ -0,0 +1,13 @@ +type: object +title: Attestation preferences for registration +properties: + conveyance_preference: + type: string + title: Conveyance preference + enterprise_approved_ids: + type: array + title: >- + Enterprise-approved IDs (optional allowlist when enterprise attestation is + used) + items: + type: string diff --git a/openapi/components/schemas/WebAuthConfigurationAuthenticatorSelection.yaml b/openapi/components/schemas/WebAuthConfigurationAuthenticatorSelection.yaml new file mode 100644 index 000000000..20f5f947d --- /dev/null +++ b/openapi/components/schemas/WebAuthConfigurationAuthenticatorSelection.yaml @@ -0,0 +1,7 @@ +type: object +properties: + authenticator_attachment: + type: string + user_verification: + type: string + title: User verification requirement diff --git a/openapi/components/schemas/WebAuthConfigurationAuthenticators.yaml b/openapi/components/schemas/WebAuthConfigurationAuthenticators.yaml new file mode 100644 index 000000000..5e0173da8 --- /dev/null +++ b/openapi/components/schemas/WebAuthConfigurationAuthenticators.yaml @@ -0,0 +1,50 @@ +type: object +properties: + desired_authenticator_status: + description: >- + provides the list of statuses which are considered undesirable for status + report validation purposes. Should be used with validate_status set to + true. + type: array + items: + type: string + default: '[]' + undesired_authenticator_status: + description: >- + provides the list of statuses which are considered undesirable for status + report validation purposes. Should be used with validate_status set to + true. + type: array + items: + type: string + default: >- + ['ATTESTATION_KEY_COMPROMISE', 'USER_VERIFICATION_BYPASS', + 'USER_KEY_REMOTE_COMPROMISE', 'USER_KEY_PHYSICAL_COMPROMISE', 'REVOKED'] + validate_anchors: + description: >- + when set to true enables the validation of the attestation statement + against the trust anchor from the metadata statement. + type: boolean + validate_attestation_type: + description: >- + when set to true enables the validation of the attestation statements type + against the known types the authenticator can produce. + type: boolean + validate_entry: + description: >- + requires that the provided metadata has an entry for the given + authenticator to be considered valid. By default an AAGUID which has a + zero value should fail validation if validate_entry_permit_zero_aaguid is + not provided with the value of true. + type: boolean + validate_entry_permit_zero_aaguid: + description: >- + is an option that permits a zero'd AAGUID from an attestation statement to + automatically pass metadata validations. Generally helpful to use with + validate_entry. + type: boolean + validate_status: + description: >- + when set to true enables the validation of the attestation statements + AAGUID against the desired and undesired lists + type: boolean diff --git a/openapi/components/schemas/WebAuthConfigurationRp.yaml b/openapi/components/schemas/WebAuthConfigurationRp.yaml new file mode 100644 index 000000000..963500b81 --- /dev/null +++ b/openapi/components/schemas/WebAuthConfigurationRp.yaml @@ -0,0 +1,19 @@ +type: object +title: Rp contains relying party identifiers and origins +properties: + ids: + type: array + title: >- + Relying party IDs (derived from environment domain and verified custom + domain) + + At least one required; must be hostnames without scheme or path + items: + type: string + origins: + type: array + title: |- + Allowed origins corresponding to the RP IDs (https://) + At least one required; must be HTTPS origins + items: + type: string diff --git a/openapi/components/schemas/WebAuthConfigurationTimeout.yaml b/openapi/components/schemas/WebAuthConfigurationTimeout.yaml new file mode 100644 index 000000000..317950b6a --- /dev/null +++ b/openapi/components/schemas/WebAuthConfigurationTimeout.yaml @@ -0,0 +1,18 @@ +type: object +properties: + login: + description: Login timeout duration + type: string + default: '"300s"' + login_uvd: + description: Login timeout duration when user verification is discouraged + type: string + default: '"300s"' + registration: + description: Registration timeout duration + type: string + default: '"300s"' + registration_uvd: + description: Registration timeout duration when user verification is discouraged + type: string + default: '"300s"' diff --git a/openapi/components/schemas/WebAuthnCredentialAuthenticator.yaml b/openapi/components/schemas/WebAuthnCredentialAuthenticator.yaml new file mode 100644 index 000000000..802493091 --- /dev/null +++ b/openapi/components/schemas/WebAuthnCredentialAuthenticator.yaml @@ -0,0 +1,21 @@ +type: object +properties: + aaguid: + description: Authenticator Attestation GUID (AAGUID) identifying the device model + type: string + attachment: + description: 'Attachment type: "platform" (built-in) or "cross-platform"' + type: string + examples: + - platform + icon_dark: + description: Icon URL for dark theme display + type: string + icon_light: + description: Icon URL for light theme display + type: string + name: + description: Human-readable name of the authenticator model + type: string + examples: + - Apple Touch ID diff --git a/openapi/components/schemas/WebAuthnCredentialAuthenticatorFlags.yaml b/openapi/components/schemas/WebAuthnCredentialAuthenticatorFlags.yaml new file mode 100644 index 000000000..8504e0e85 --- /dev/null +++ b/openapi/components/schemas/WebAuthnCredentialAuthenticatorFlags.yaml @@ -0,0 +1,14 @@ +type: object +properties: + backup_eligible: + description: Whether this credential can be backed up to another device + type: boolean + backup_state: + description: Whether this credential was synced or backed up + type: boolean + user_present: + description: Whether the user was present during authentication + type: boolean + user_verified: + description: Whether the user was verified (e.g., fingerprint, PIN) + type: boolean diff --git a/openapi/components/schemas/WebAuthnCredentialClientInfo.yaml b/openapi/components/schemas/WebAuthnCredentialClientInfo.yaml new file mode 100644 index 000000000..6a3cff16f --- /dev/null +++ b/openapi/components/schemas/WebAuthnCredentialClientInfo.yaml @@ -0,0 +1,22 @@ +type: object +properties: + city: + description: City name + type: string + examples: + - San Francisco + ip: + description: IP address from which credential was registered + type: string + examples: + - 192.0.2.1 + region: + description: Geographic region (e.g., "US") + type: string + examples: + - US + region_subdivision: + description: Regional subdivision (e.g., "CA") + type: string + examples: + - CA diff --git a/openapi/components/schemas/WebAuthnCredentialUserAgent.yaml b/openapi/components/schemas/WebAuthnCredentialUserAgent.yaml new file mode 100644 index 000000000..ca5827224 --- /dev/null +++ b/openapi/components/schemas/WebAuthnCredentialUserAgent.yaml @@ -0,0 +1,38 @@ +type: object +properties: + browser: + description: Browser name (e.g., "Chrome", "Safari") + type: string + examples: + - Chrome + browser_version: + description: Browser version number + type: string + examples: + - 120.0.6099.129 + device_model: + description: Device model if available + type: string + examples: + - iPhone15,2 + device_type: + description: 'Device type: "desktop", "mobile", or "tablet"' + type: string + examples: + - mobile + os: + description: Operating system name (e.g., "Windows", "iOS") + type: string + examples: + - macOS + os_version: + description: Operating system version + type: string + examples: + - '14.2' + raw: + description: Raw user agent string from the browser + type: string + url: + description: Parsed user agent URL reference + type: string diff --git a/openapi/components/schemas/WebAuthnServiceUpdateCredentialBody.yaml b/openapi/components/schemas/WebAuthnServiceUpdateCredentialBody.yaml new file mode 100644 index 000000000..030fe286c --- /dev/null +++ b/openapi/components/schemas/WebAuthnServiceUpdateCredentialBody.yaml @@ -0,0 +1,7 @@ +type: object +properties: + display_name: + description: Human-friendly name for this credential (1-120 characters) + type: string + examples: + - My iPhone 15 Pro diff --git a/openapi/components/schemas/authpasswordlessPasswordlessType.yaml b/openapi/components/schemas/authpasswordlessPasswordlessType.yaml new file mode 100644 index 000000000..b34ad286a --- /dev/null +++ b/openapi/components/schemas/authpasswordlessPasswordlessType.yaml @@ -0,0 +1,5 @@ +type: string +enum: + - OTP + - LINK + - LINK_OTP diff --git a/openapi/components/schemas/clientsClientSecret.yaml b/openapi/components/schemas/clientsClientSecret.yaml new file mode 100644 index 000000000..17cfe1fb3 --- /dev/null +++ b/openapi/components/schemas/clientsClientSecret.yaml @@ -0,0 +1,80 @@ +description: >- + A secure credential used for authenticating an API client. Each client can + have multiple secrets for key rotation purposes. +type: object +title: Client Secret +properties: + create_time: + description: >- + The timestamp when this secret was created. This field is automatically + set by the server and cannot be modified. + type: string + format: date-time + examples: + - '2024-01-05T14:48:00Z' + created_by: + description: >- + The identifier of the user or system that created this secret. This field + helps track who created the secret for audit and compliance purposes. + type: string + examples: + - user_12345 + expire_time: + description: >- + The timestamp when this secret will expire. After this time, the secret + cannot be used for authentication regardless of its status. If not set, + the secret does not expire. + type: string + format: date-time + examples: + - '2025-01-05T14:48:00Z' + id: + description: >- + The unique identifier for this client secret. This ID is used to reference + the secret in API requests for management operations like updating or + deleting the secret. + type: string + examples: + - sec_1234abcd5678efgh + last_used_time: + description: >- + The timestamp when this secret was last used for authentication. This + field helps track secret usage for security monitoring and identifying + unused secrets that may be candidates for rotation. + type: string + format: date-time + examples: + - '2024-02-15T10:30:00Z' + plain_secret: + description: >- + The full plaintext secret value. This field is only populated when the + secret is first created and is never stored by the server. It must be + securely stored by the client application as it cannot be retrieved again. + type: string + examples: + - sec_1234567890abcdefghijklmnopqrstuvwxyz + secret_suffix: + description: >- + A suffix that helps identify this secret. This is the last few characters + of the full secret value but is not sufficient for authentication. Helps + identify which secret is being used in logs and debugging. + type: string + examples: + - xyzw + status: + description: >- + The current status of this secret. A secret must be ACTIVE to be used for + authentication. INACTIVE secrets cannot be used for authentication but are + retained for audit purposes. + $ref: ./clientsClientSecretStatus.yaml + examples: + - INACTIVE + update_time: + description: >- + The timestamp when this secret was last updated. This field is + automatically updated by the server when the secret's status changes or + other properties are modified. + type: string + format: date-time + examples: + - '2024-01-10T09:12:00Z' diff --git a/openapi/components/schemas/clientsClientSecretStatus.yaml b/openapi/components/schemas/clientsClientSecretStatus.yaml new file mode 100644 index 000000000..0a215fb6d --- /dev/null +++ b/openapi/components/schemas/clientsClientSecretStatus.yaml @@ -0,0 +1,10 @@ +description: >- + ClientSecretStatus indicates whether a client secret can be used for + authentication. + + ACTIVE secrets can be used for authentication while INACTIVE secrets cannot. + + - INACTIVE: The secret is inactive and cannot be used for authentication +type: string +enum: + - INACTIVE diff --git a/openapi/components/schemas/clientsCreateOrganizationClientResponse.yaml b/openapi/components/schemas/clientsCreateOrganizationClientResponse.yaml new file mode 100644 index 000000000..aa62ee347 --- /dev/null +++ b/openapi/components/schemas/clientsCreateOrganizationClientResponse.yaml @@ -0,0 +1,10 @@ +type: object +properties: + client: + description: Details of the created client + $ref: ./clientsM2MClient.yaml + plain_secret: + description: Client secret value (only returned once at creation) + type: string + examples: + - CdExsdErfccxDDssddfffgfeFHH1 diff --git a/openapi/components/schemas/clientsCreateOrganizationClientSecretResponse.yaml b/openapi/components/schemas/clientsCreateOrganizationClientSecretResponse.yaml new file mode 100644 index 000000000..2f8d8cf7c --- /dev/null +++ b/openapi/components/schemas/clientsCreateOrganizationClientSecretResponse.yaml @@ -0,0 +1,10 @@ +type: object +properties: + plain_secret: + description: Client secret value (only returned once at creation) + type: string + examples: + - m2morg_client_secret_xyz123 + secret: + description: Details of the created client secret + $ref: ./clientsClientSecret.yaml diff --git a/openapi/components/schemas/clientsCustomClaim.yaml b/openapi/components/schemas/clientsCustomClaim.yaml new file mode 100644 index 000000000..4fbadcea5 --- /dev/null +++ b/openapi/components/schemas/clientsCustomClaim.yaml @@ -0,0 +1,16 @@ +type: object +properties: + key: + description: >- + The name of the custom claim. Must be between 1 and 128 characters. Use + descriptive names that clearly indicate the claim's purpose. + type: string + examples: + - environment + value: + description: >- + The value of the custom claim. This value will be included in access + tokens issued to the client. + type: string + examples: + - production diff --git a/openapi/components/schemas/clientsGetOrganizationClientResponse.yaml b/openapi/components/schemas/clientsGetOrganizationClientResponse.yaml new file mode 100644 index 000000000..d7696c516 --- /dev/null +++ b/openapi/components/schemas/clientsGetOrganizationClientResponse.yaml @@ -0,0 +1,5 @@ +type: object +properties: + client: + description: Details of the requested client + $ref: ./clientsM2MClient.yaml diff --git a/openapi/components/schemas/clientsListOrganizationClientsResponse.yaml b/openapi/components/schemas/clientsListOrganizationClientsResponse.yaml new file mode 100644 index 000000000..0f314ece1 --- /dev/null +++ b/openapi/components/schemas/clientsListOrganizationClientsResponse.yaml @@ -0,0 +1,39 @@ +description: >- + Response message containing a paginated list of API clients for the specified + organization. +type: object +title: List Organization Clients Response +properties: + clients: + description: >- + List of API client objects for the organization. Each client includes its + configuration, metadata, and active secrets (without exposing actual + secret values). + type: array + title: List of organization API clients + items: + type: object + $ref: ./clientsM2MClient.yaml + next_page_token: + description: >- + Pagination token for the next page of results. Use this token to fetch the + next page. + type: string + title: Pagination token for the next page of results + examples: + - + prev_page_token: + description: >- + Pagination token for the previous page of results. Use this token to fetch + the previous page. + type: string + title: Pagination token for the previous page of results + examples: + - + total_size: + description: Total number of API clients in the organization. + type: integer + format: int64 + title: Total number of clients in the organization + examples: + - 30 diff --git a/openapi/components/schemas/clientsM2MClient.yaml b/openapi/components/schemas/clientsM2MClient.yaml new file mode 100644 index 000000000..3d8019c6e --- /dev/null +++ b/openapi/components/schemas/clientsM2MClient.yaml @@ -0,0 +1,132 @@ +type: object +properties: + audience: + description: >- + The intended recipients of access tokens issued to this client. Each + audience value should be a URI that identifies an API or service. + type: array + items: + type: string + examples: + - - https://api.example.com + client_id: + description: >- + The unique identifier for this API client. This ID is used to identify the + client in API requests and logs. It is automatically generated when the + client is created and cannot be modified. + type: string + examples: + - m2morg_1231234233424344 + create_time: + description: >- + The timestamp when this API client was created. This field is + automatically set by the server and cannot be modified. + type: string + format: date-time + examples: + - '2024-01-05T14:48:00Z' + custom_claims: + description: >- + Additional claims included in access tokens issued to this client. These + claims provide context about the client and can be used for authorization + decisions. + type: array + items: + type: object + $ref: ./clientsCustomClaim.yaml + description: + description: >- + A detailed description of the client's purpose and usage. This helps + administrators understand what the client is used for. + type: string + examples: + - Service account for automated deployment processes + expiry: + description: Expiry time in seconds for the token generated by the client + type: string + format: int64 + examples: + - 3600 + is_cimd: + description: >- + Indicates if the client was created via Client ID Metadata Document + (CIMD). CIMD clients can update their own configuration according to the + CIMD specification. + type: boolean + examples: + - false + is_dcr: + description: >- + Indicates if the client was created via Dynamic Client Registration (DCR). + Clients created through DCR may have different management and lifecycle + policies compared to those created manually. + type: boolean + examples: + - false + metadata_uri: + description: >- + The URI to the client's metadata, which is utilized to obtain the client's + configuration details + type: string + examples: + - https://example.com/client-metadata.json + name: + description: >- + The display name of the API client. This name helps identify the client in + the dashboard and logs. + type: string + examples: + - GitHub Actions Deployment Service + organization_id: + description: >- + The ID of the organization that owns this API client. This ID is used to + associate the client with the correct organization and enforce + organization-specific access controls. + type: string + examples: + - org_1231234233424344 + redirect_uris: + description: >- + The redirect URI for this API client. This URI is used in the OAuth 2.0 + authorization flow to redirect users after authentication. + type: array + items: + type: string + examples: + - - https://example.com/callback + resource_id: + description: >- + The ID of the resource associated with this M2M client. This field is used + to link the client to a specific resource in the system. + type: string + examples: + - app_1231234233424344 + scopes: + description: >- + The OAuth 2.0 scopes granted to this client. These scopes determine what + resources and actions the client can access. + type: array + items: + type: string + examples: + - - deploy:resources + - read:deployments + secrets: + description: >- + List of client secrets associated with this client. Each secret can be + used for authentication, but only the most recently created secret is + typically active. Secrets are stored securely and their values are never + returned after creation. + type: array + items: + type: object + $ref: ./clientsClientSecret.yaml + update_time: + description: >- + The timestamp when this API client was last updated. This field is + automatically updated by the server whenever the client's configuration + changes. + type: string + format: date-time + examples: + - '2024-01-05T14:48:00Z' diff --git a/openapi/components/schemas/clientsOrganizationClient.yaml b/openapi/components/schemas/clientsOrganizationClient.yaml new file mode 100644 index 000000000..924cb27cd --- /dev/null +++ b/openapi/components/schemas/clientsOrganizationClient.yaml @@ -0,0 +1,60 @@ +type: object +properties: + audience: + description: >- + The intended recipients of the access tokens issued to this client. Each + audience value should be a URI that identifies the API or service that + will validate the token. + type: array + items: + type: string + examples: + - - https://api.example.com/api/analytics + - https://deployment-api.acmecorp.com + custom_claims: + description: >- + Additional claims to be included in access tokens issued to this client. + These claims provide context about the client and can be used for + authorization decisions. Keep claims minimal to avoid increasing token + size. + type: array + items: + type: object + $ref: ./clientsCustomClaim.yaml + examples: + - - key: environment + value: production + - key: service + value: deployment + description: + description: >- + A detailed explanation of the client's purpose and usage. This helps + administrators understand what the client is used for and who manages it. + type: string + examples: + - Service account for GitHub Actions to deploy resources to production + expiry: + description: Expiry time in seconds for the token generated by the client + type: string + format: int64 + examples: + - 3600 + name: + description: >- + A descriptive name for the API client that helps identify its purpose. + This name is displayed in the dashboard and logs. Must be between 1 and + 128 characters. + type: string + examples: + - GitHub Actions Deployment Service + scopes: + description: >- + OAuth 2.0 scopes that define the permissions granted to this client. Each + scope represents a specific permission or set of permissions. The client + can only access resources that match its granted scopes. + type: array + items: + type: string + examples: + - - deploy:resources + - read:deployments diff --git a/openapi/components/schemas/clientsUpdateOrganizationClientResponse.yaml b/openapi/components/schemas/clientsUpdateOrganizationClientResponse.yaml new file mode 100644 index 000000000..1fd764525 --- /dev/null +++ b/openapi/components/schemas/clientsUpdateOrganizationClientResponse.yaml @@ -0,0 +1,5 @@ +type: object +properties: + client: + description: Updated details of the client + $ref: ./clientsM2MClient.yaml diff --git a/openapi/components/schemas/commonsExternalIdentity.yaml b/openapi/components/schemas/commonsExternalIdentity.yaml new file mode 100644 index 000000000..92be9028f --- /dev/null +++ b/openapi/components/schemas/commonsExternalIdentity.yaml @@ -0,0 +1,59 @@ +type: object +properties: + connection_id: + description: >- + Unique identifier for the external identity connection. Immutable and + read-only. + type: string + readOnly: true + examples: + - conn_1234abcd5678efgh + connection_provider: + description: Type of the identity provider. + $ref: ./commonsIdentityProviderType.yaml + readOnly: true + examples: + - GOOGLE + connection_type: + description: Name of the external identity connection. + type: string + readOnly: true + examples: + - OAUTH + connection_user_id: + description: >- + Unique identifier for the user in the external identity provider system. + Immutable and read-only. + type: string + readOnly: true + examples: + - ext_user_12345 + created_time: + description: >- + Timestamp when this external identity connection was first created. + Immutable and read-only. + type: string + format: date-time + readOnly: true + is_social: + description: >- + Indicates if the identity provider is a social provider (true) or + enterprise/custom provider (false). Read-only. + type: boolean + readOnly: true + examples: + - true + last_login_time: + description: >- + Timestamp of the user's last successful login via this external identity + provider. Automatically updated by the system. + type: string + format: date-time + readOnly: true + last_synced_time: + description: >- + Timestamp of the last data synchronization for this external identity from + the provider. Automatically updated by the system. + type: string + format: date-time + readOnly: true diff --git a/openapi/components/schemas/commonsIdentityProviderType.yaml b/openapi/components/schemas/commonsIdentityProviderType.yaml new file mode 100644 index 000000000..5f6b76ebc --- /dev/null +++ b/openapi/components/schemas/commonsIdentityProviderType.yaml @@ -0,0 +1,18 @@ +type: string +enum: + - OKTA + - GOOGLE + - MICROSOFT_AD + - AUTH0 + - ONELOGIN + - PING_IDENTITY + - JUMPCLOUD + - CUSTOM + - GITHUB + - GITLAB + - LINKEDIN + - SALESFORCE + - MICROSOFT + - IDP_SIMULATOR + - SCALEKIT + - ADFS diff --git a/openapi/components/schemas/commonsMembershipStatus.yaml b/openapi/components/schemas/commonsMembershipStatus.yaml new file mode 100644 index 000000000..905ac743e --- /dev/null +++ b/openapi/components/schemas/commonsMembershipStatus.yaml @@ -0,0 +1,6 @@ +type: string +enum: + - ACTIVE + - INACTIVE + - PENDING_INVITE + - INVITE_EXPIRED diff --git a/openapi/components/schemas/commonsOrganizationMembership.yaml b/openapi/components/schemas/commonsOrganizationMembership.yaml new file mode 100644 index 000000000..cb9a2074d --- /dev/null +++ b/openapi/components/schemas/commonsOrganizationMembership.yaml @@ -0,0 +1,82 @@ +type: object +properties: + accepted_at: + description: Timestamp when the user accepted the invitation. + type: string + format: date-time + created_at: + description: Timestamp when the invitation was created. + type: string + format: date-time + display_name: + description: >- + Organization display name. This field stores a user-friendly name for the + organization that may be different from the formal name, often used for UI + display purposes. + type: string + examples: + - Acme Corporation + expires_at: + description: Timestamp when the invitation expired. + type: string + format: date-time + inviter_email: + description: ID of the user who invited this user. + type: string + join_time: + description: >- + Timestamp when the membership was created. Automatically set by the + server. + type: string + format: date-time + membership_status: + $ref: ./commonsMembershipStatus.yaml + metadata: + description: >- + Custom key-value pairs for storing additional user context. Keys (3-25 + chars), values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - department: engineering + location: nyc-office + name: + description: >- + Organization name. This field stores the formal organization name used for + identification and display purposes. + type: string + examples: + - AcmeCorp + organization_id: + description: Unique identifier for the organization. Immutable and read-only. + type: string + examples: + - org_1234abcd5678efgh + permissions: + description: >- + Effective permissions granted to the user within the organization + (including inherited permissions from assigned roles). Lists the specific + actions and access rights the user can perform. + type: array + items: + type: string + examples: + - - read_projects + - write_tasks + - manage_users + provisioning_method: + description: |- + How the user was provisioned. + Possible values: + - `jit_using_sso` (Just-in-time provisioning during SSO login) + - `allowed_email_domain` (User joined via allowed email domain matching) + - `org_creator` (User created the organization) + - `direct_provision` (User was directly provisioned via API or SCIM) + - `invitation` (User was invited and accepted an invitation) + type: string + roles: + type: array + items: + type: object + $ref: ./commonsRole.yaml diff --git a/openapi/components/schemas/commonsRegionCode.yaml b/openapi/components/schemas/commonsRegionCode.yaml new file mode 100644 index 000000000..a3fe41f0e --- /dev/null +++ b/openapi/components/schemas/commonsRegionCode.yaml @@ -0,0 +1,4 @@ +type: string +enum: + - US + - EU diff --git a/openapi/components/schemas/commonsRole.yaml b/openapi/components/schemas/commonsRole.yaml new file mode 100644 index 000000000..a9188895c --- /dev/null +++ b/openapi/components/schemas/commonsRole.yaml @@ -0,0 +1,21 @@ +type: object +properties: + display_name: + description: Human-readable name for the role + type: string + examples: + - Dev Team + id: + description: Role ID + type: string + readOnly: true + examples: + - role_79643236410327240 + name: + description: >- + Attribute name/identifier for the role used in system operations and API + calls. This should be a machine-readable identifier that follows naming + conventions. + type: string + examples: + - team_dev diff --git a/openapi/components/schemas/commonsTimeUnit.yaml b/openapi/components/schemas/commonsTimeUnit.yaml new file mode 100644 index 000000000..9ee2a6587 --- /dev/null +++ b/openapi/components/schemas/commonsTimeUnit.yaml @@ -0,0 +1,5 @@ +type: string +enum: + - MINUTES + - HOURS + - DAYS diff --git a/openapi/components/schemas/commonsUserProfile.yaml b/openapi/components/schemas/commonsUserProfile.yaml new file mode 100644 index 000000000..09674b31f --- /dev/null +++ b/openapi/components/schemas/commonsUserProfile.yaml @@ -0,0 +1,163 @@ +type: object +properties: + custom_attributes: + description: >- + Custom attributes for extended user profile data and application-specific + information. This field stores business-specific user data like + department, job title, security clearances, project assignments, or any + other organizational attributes your application requires. Unlike system + metadata, these attributes are typically managed by administrators or + applications and are visible to end users for personalization and business + logic. Keys must be 3-25 characters, values must be 1-256 characters, with + a maximum of 20 key-value pairs. + type: object + additionalProperties: + type: string + examples: + - department: engineering + security_clearance: level2 + email_verified: + description: >- + Indicates if the user's email address has been verified. Automatically + updated by the system. + type: boolean + readOnly: true + examples: + - true + external_identities: + description: List of external identity connections associated with the user profile. + type: array + items: + type: object + $ref: ./commonsExternalIdentity.yaml + readOnly: true + family_name: + description: >- + The user's family name (last name or surname). This field stores the + user's last name and is combined with the given name to create the full + display name. The family name is used in formal communications, user + listings, and organizational directories throughout the system. Maximum + 255 characters allowed. + type: string + examples: + - Doe + gender: + description: >- + The user's gender identity information. This field stores the user's + gender identity for personalization, compliance reporting, or + organizational analytics purposes. This field supports any string value to + accommodate diverse gender identities and should be handled with + appropriate privacy considerations according to your organization's + policies and applicable regulations. + type: string + examples: + - male + given_name: + description: >- + The user's given name (first name). This field stores the user's first + name and is used for personalization, display purposes, and when + generating the full display name. The given name appears in user + interfaces, formal communications, and user listings throughout the + system. Maximum 255 characters allowed. + type: string + examples: + - John + groups: + description: >- + The list of group names the user belongs to within the organization. This + field stores the user's group memberships for role-based access control, + team assignments, and organizational structure. Groups are typically used + for permission management, collaborative access, and organizational + hierarchy. Each group name represents a distinct organizational unit or + team that the user is associated with. + type: array + items: + type: string + examples: + - - admin + - developer + id: + description: >- + Unique system-generated identifier for the user profile. Immutable and + read-only. + type: string + readOnly: true + examples: + - usr_profile_1234abcd5678efgh + locale: + description: >- + The user's preferred language and region settings using BCP-47 format + codes. This field customizes the user's experience with localized content, + date formats, number formatting, and UI language throughout the system. + When not specified, the user inherits the organization's default locale + settings. Common values include `en-US`, `en-GB`, `fr-FR`, `de-DE`, and + `es-ES`. + type: string + examples: + - en-US + metadata: + description: >- + Raw attributes received from identity providers during authentication. + This field stores the original user profile data as received from external + IdP systems (SAML, OIDC, etc.) including provider-specific claims and + attributes. These fields preserve the complete set of attributes received + from the identity source and are used for mapping, synchronization, and + audit purposes. Keys must be 3-25 characters, values must be 1-256 + characters, with a maximum of 20 key-value pairs. + type: object + additionalProperties: + type: string + examples: + - department: engineering + employee_type: full-time + idp_user_id: '12345' + name: + description: >- + The user's complete display name in formatted form. This field stores the + full name as a single string and is typically used when you want to set + the complete name rather than using separate given and family names. This + name appears in user interfaces, reports, directory listings, and anywhere + a formatted display name is needed. This field serves as a formatted + display name that complements the individual given_name and family_name + fields. + type: string + examples: + - John Michael Doe + phone_number: + description: >- + The user's phone number in E.164 international format. This field stores + the phone number for user contact and identification purposes. The phone + number must include the country code and be formatted according to E.164 + standards (e.g., `+1` for US numbers). This field is optional. + type: string + examples: + - '+14155552671' + phone_number_verified: + description: >- + Indicates if the user's phone number has been verified. Automatically + updated by the system. + type: boolean + readOnly: true + examples: + - true + picture: + description: >- + The URL to the user's profile picture or avatar image. This field stores + the location of the user's profile photo that appears in user interfaces, + directory listings, and collaborative features throughout the system. The + URL should point to a publicly accessible image file. Supported formats + typically include JPEG, PNG, and GIF. This image is used for visual + identification and personalization across the platform. + type: string + examples: + - https://example.com/avatar.jpg + preferred_username: + description: >- + The user's preferred username for display and identification purposes. + This field stores a custom username that the user prefers to be known by, + which may differ from their email or formal name. This username appears in + user interfaces, mentions, informal communications, and collaborative + features throughout the system. Maximum 512 characters allowed. + type: string + examples: + - johndoe diff --git a/openapi/components/schemas/connected_accountsAuthorizationDetails.yaml b/openapi/components/schemas/connected_accountsAuthorizationDetails.yaml new file mode 100644 index 000000000..a892527ef --- /dev/null +++ b/openapi/components/schemas/connected_accountsAuthorizationDetails.yaml @@ -0,0 +1,12 @@ +type: object +title: Authentication credentials container supporting multiple auth types +properties: + google_dwd: + title: Google Domain-Wide Delegation credentials + $ref: ./connected_accountsGoogleDWDAuth.yaml + oauth_token: + title: OAuth 2.0 credentials + $ref: ./connected_accountsOauthToken.yaml + static_auth: + title: Static authentication credentials + $ref: ./connected_accountsStaticAuth.yaml diff --git a/openapi/components/schemas/connected_accountsConnectedAccount.yaml b/openapi/components/schemas/connected_accountsConnectedAccount.yaml new file mode 100644 index 000000000..d970821cf --- /dev/null +++ b/openapi/components/schemas/connected_accountsConnectedAccount.yaml @@ -0,0 +1,86 @@ +type: object +properties: + api_config: + description: >- + Optional JSON configuration for connector-specific API settings such as + rate limits, custom endpoints, or feature flags. + type: object + examples: + - base_url: https://api.custom-domain.com + rate_limit: 1000 + timeout: 30 + authorization_details: + description: >- + Sensitive authentication credentials including access tokens, refresh + tokens, and scopes. Contains either OAuth tokens or static auth details. + $ref: ./connected_accountsAuthorizationDetails.yaml + authorization_type: + description: >- + Type of authorization mechanism used. Specifies whether this connection + uses OAuth, API keys, bearer tokens, or other auth methods. + $ref: ./connected_accountsConnectorType.yaml + connection_id: + description: >- + Reference to the parent connection configuration. Links this account to a + specific connector setup in your environment. + type: string + examples: + - conn_24834495392086178 + connector: + description: >- + Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates + which third-party application this account connects to. + type: string + examples: + - notion + id: + description: >- + Unique Scalekit-generated identifier for this connected account. Always + prefixed with 'ca_'. + type: string + examples: + - ca_24834495392086178 + identifier: + description: >- + The unique identifier for this account in the third-party service. + Typically an email address, user ID, or workspace identifier. + type: string + examples: + - user@example.com + last_used_at: + description: >- + Timestamp when this connected account was last used to make an API call. + Useful for tracking active connections. + type: string + format: date-time + examples: + - '2024-03-20T14:30:00Z' + provider: + description: >- + OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies + which authentication service manages this connection. + type: string + examples: + - google + status: + description: >- + Current status of the connected account. Indicates if the account is + active, expired, pending authorization, or pending user identity + verification. + $ref: ./connected_accountsConnectorStatus.yaml + token_expires_at: + description: >- + Expiration timestamp for the access token. After this time, the token must + be refreshed or re-authorized. + type: string + format: date-time + examples: + - '2024-12-31T23:59:59Z' + updated_at: + description: >- + Timestamp when this connected account was last modified. Updated whenever + credentials or configuration changes. + type: string + format: date-time + examples: + - '2024-03-20T15:04:05Z' diff --git a/openapi/components/schemas/connected_accountsConnectedAccountForList.yaml b/openapi/components/schemas/connected_accountsConnectedAccountForList.yaml new file mode 100644 index 000000000..984b7eb53 --- /dev/null +++ b/openapi/components/schemas/connected_accountsConnectedAccountForList.yaml @@ -0,0 +1,54 @@ +type: object +title: >- + Connected account summary for list operations - excludes sensitive + authorization details +properties: + authorization_type: + description: Authorization mechanism type. + $ref: ./connected_accountsConnectorType.yaml + connection_id: + description: Parent connection configuration reference. + type: string + examples: + - conn_24834495392086178 + connector: + description: Connector identifier. + type: string + examples: + - notion + id: + description: Unique connected account identifier. + type: string + examples: + - ca_24834495392086178 + identifier: + description: The unique identifier for this account in the third-party service. + type: string + examples: + - user@example.com + last_used_at: + description: Last usage timestamp. + type: string + format: date-time + examples: + - '2024-03-20T14:30:00Z' + provider: + description: OAuth provider name (e.g., 'google', 'microsoft'). + type: string + examples: + - google + status: + description: Current connection status. + $ref: ./connected_accountsConnectorStatus.yaml + token_expires_at: + description: Token expiration timestamp. + type: string + format: date-time + examples: + - '2024-12-31T23:59:59Z' + updated_at: + description: Last modification timestamp. + type: string + format: date-time + examples: + - '2024-03-20T15:04:05Z' diff --git a/openapi/components/schemas/connected_accountsConnectorStatus.yaml b/openapi/components/schemas/connected_accountsConnectorStatus.yaml new file mode 100644 index 000000000..575134b19 --- /dev/null +++ b/openapi/components/schemas/connected_accountsConnectorStatus.yaml @@ -0,0 +1,15 @@ +description: |- + - ACTIVE: Account is connected and credentials are valid + - EXPIRED: Access token has expired and needs refresh + - PENDING_AUTH: Account awaiting user authorization (re-auth initiated) + - PENDING_VERIFICATION: OAuth complete; awaiting user identity verification + before activation + - DISCONNECTED: Account has been manually disconnected +type: string +title: Status of a connected account indicating its current state +enum: + - ACTIVE + - EXPIRED + - PENDING_AUTH + - PENDING_VERIFICATION + - DISCONNECTED diff --git a/openapi/components/schemas/connected_accountsConnectorType.yaml b/openapi/components/schemas/connected_accountsConnectorType.yaml new file mode 100644 index 000000000..41cfdf85c --- /dev/null +++ b/openapi/components/schemas/connected_accountsConnectorType.yaml @@ -0,0 +1,22 @@ +description: |- + - OAUTH: OAuth 2.0 authorization with access and refresh tokens + - API_KEY: Static API key authentication + - BASIC_AUTH: HTTP Basic Authentication (username/password) + - BEARER_TOKEN: Bearer token authentication + - CUSTOM: Custom authentication mechanism + - BASIC: Basic authentication (alias) + - OAUTH_M2M: OAuth 2.0 client credentials (machine-to-machine) + - TRELLO_OAUTH1: Trello token-based OAuth1-style browser authorization + - GOOGLE_DWD: Google Domain-Wide Delegation +type: string +title: Type of authentication mechanism used for the connected account +enum: + - OAUTH + - API_KEY + - BASIC_AUTH + - BEARER_TOKEN + - CUSTOM + - BASIC + - OAUTH_M2M + - TRELLO_OAUTH1 + - GOOGLE_DWD diff --git a/openapi/components/schemas/connected_accountsCreateConnectedAccountRequest.yaml b/openapi/components/schemas/connected_accountsCreateConnectedAccountRequest.yaml new file mode 100644 index 000000000..ebd66307b --- /dev/null +++ b/openapi/components/schemas/connected_accountsCreateConnectedAccountRequest.yaml @@ -0,0 +1,38 @@ +type: object +properties: + connected_account: + description: Details of the connected account to create + $ref: ./v1connected_accountsCreateConnectedAccount.yaml + examples: + - authorization_details: + oauth_token: + access_token: ... + refresh_token: ... + scopes: + - read + - write + authorization_type: OAUTH2 + connector: + description: >- + Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric + characters, spaces, hyphens, underscores, and colons are allowed. + type: string + examples: + - notion + identifier: + description: >- + The unique identifier for the connected account within the third-party + service (e.g., email address, user ID, workspace identifier). + type: string + examples: + - user@example.com + organization_id: + description: Organization ID for the connector + type: string + examples: + - org_121312434123312 + user_id: + description: User ID for the connector + type: string + examples: + - user_121312434123312 diff --git a/openapi/components/schemas/connected_accountsCreateConnectedAccountResponse.yaml b/openapi/components/schemas/connected_accountsCreateConnectedAccountResponse.yaml new file mode 100644 index 000000000..6d6b28799 --- /dev/null +++ b/openapi/components/schemas/connected_accountsCreateConnectedAccountResponse.yaml @@ -0,0 +1,7 @@ +type: object +properties: + connected_account: + description: >- + The newly created connected account with its unique identifier, status, + and complete authorization details including access tokens. + $ref: ./connected_accountsConnectedAccount.yaml diff --git a/openapi/components/schemas/connected_accountsDeleteConnectedAccountRequest.yaml b/openapi/components/schemas/connected_accountsDeleteConnectedAccountRequest.yaml new file mode 100644 index 000000000..c4bcbd888 --- /dev/null +++ b/openapi/components/schemas/connected_accountsDeleteConnectedAccountRequest.yaml @@ -0,0 +1,31 @@ +type: object +properties: + connector: + description: >- + Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric + characters, spaces, hyphens, underscores, and colons are allowed. + type: string + examples: + - notion + id: + description: Unique identifier for the connected account to delete + type: string + examples: + - ca_123 + identifier: + description: >- + The unique identifier for the connected account within the third-party + service (e.g., email address, user ID, workspace identifier). + type: string + examples: + - user@example.com + organization_id: + description: Organization ID for the connector + type: string + examples: + - org_121312434123312 + user_id: + description: User ID for the connector + type: string + examples: + - user_121312434123312 diff --git a/openapi/components/schemas/connected_accountsDeleteConnectedAccountResponse.yaml b/openapi/components/schemas/connected_accountsDeleteConnectedAccountResponse.yaml new file mode 100644 index 000000000..91bf3091f --- /dev/null +++ b/openapi/components/schemas/connected_accountsDeleteConnectedAccountResponse.yaml @@ -0,0 +1 @@ +type: object diff --git a/openapi/components/schemas/connected_accountsGetConnectedAccountByIdentifierResponse.yaml b/openapi/components/schemas/connected_accountsGetConnectedAccountByIdentifierResponse.yaml new file mode 100644 index 000000000..a11099d70 --- /dev/null +++ b/openapi/components/schemas/connected_accountsGetConnectedAccountByIdentifierResponse.yaml @@ -0,0 +1,8 @@ +type: object +properties: + connected_account: + description: >- + The connected account with complete details including sensitive + authorization credentials (access tokens, refresh tokens, scopes). Handle + with appropriate access controls. + $ref: ./connected_accountsConnectedAccount.yaml diff --git a/openapi/components/schemas/connected_accountsGetMagicLinkForConnectedAccountRequest.yaml b/openapi/components/schemas/connected_accountsGetMagicLinkForConnectedAccountRequest.yaml new file mode 100644 index 000000000..ecbea3d2c --- /dev/null +++ b/openapi/components/schemas/connected_accountsGetMagicLinkForConnectedAccountRequest.yaml @@ -0,0 +1,43 @@ +type: object +properties: + connector: + description: >- + Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric + characters, spaces, hyphens, underscores, and colons are allowed. + type: string + examples: + - notion + id: + description: Unique identifier for the connected account + type: string + examples: + - ca_123 + identifier: + description: >- + The unique identifier for the connected account within the third-party + service (e.g., email address, user ID, workspace identifier). + type: string + examples: + - user@example.com + organization_id: + description: Organization ID for the connector + type: string + examples: + - org_121312434123312 + state: + description: >- + Optional opaque state value. State added to the user verify redirect URL + query params to validate the user verification + type: string + examples: + - QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY= + user_id: + description: User ID for the connector + type: string + examples: + - user_121312434123312 + user_verify_url: + description: B2B app's user verify redirect URL + type: string + examples: + - https://app.yourapp.com/user/verify/callback diff --git a/openapi/components/schemas/connected_accountsGetMagicLinkForConnectedAccountResponse.yaml b/openapi/components/schemas/connected_accountsGetMagicLinkForConnectedAccountResponse.yaml new file mode 100644 index 000000000..78dcabb24 --- /dev/null +++ b/openapi/components/schemas/connected_accountsGetMagicLinkForConnectedAccountResponse.yaml @@ -0,0 +1,13 @@ +type: object +properties: + expiry: + description: Expiry timestamp for the authentication link + type: string + format: date-time + examples: + - '2024-03-20T15:04:05Z' + link: + description: Authentication link for the connector + type: string + examples: + - https://notion.com/oauth/authorize?client_id=... diff --git a/openapi/components/schemas/connected_accountsGoogleDWDAuth.yaml b/openapi/components/schemas/connected_accountsGoogleDWDAuth.yaml new file mode 100644 index 000000000..f7d1ae7e6 --- /dev/null +++ b/openapi/components/schemas/connected_accountsGoogleDWDAuth.yaml @@ -0,0 +1,37 @@ +description: >- + Google Domain-Wide Delegation authentication — used for GOOGLE_DWD + connections. + + Send only subject in requests; access_token, scopes, and token_expires_at are + response-only. +type: object +properties: + access_token: + description: >- + OAuth access token acquired via the jwt-bearer grant. Present in responses + only. + type: string + readOnly: true + examples: + - ya29.a0AfH6SMBx... + scopes: + description: OAuth scopes granted to this token. Present in responses only. + type: array + items: + type: string + readOnly: true + examples: + - - openid + - https://www.googleapis.com/auth/userinfo.email + subject: + description: >- + Email address of the Google Workspace user to impersonate via Domain-Wide + Delegation. + type: string + examples: + - user@example.com + token_expires_at: + description: When the access token expires. Present in responses only. + type: string + format: date-time + readOnly: true diff --git a/openapi/components/schemas/connected_accountsListConnectedAccountsResponse.yaml b/openapi/components/schemas/connected_accountsListConnectedAccountsResponse.yaml new file mode 100644 index 000000000..a30b5e74e --- /dev/null +++ b/openapi/components/schemas/connected_accountsListConnectedAccountsResponse.yaml @@ -0,0 +1,32 @@ +type: object +properties: + connected_accounts: + description: >- + List of connected accounts matching the filter criteria. Excludes + sensitive authorization details for security. + type: array + items: + type: object + $ref: ./connected_accountsConnectedAccountForList.yaml + next_page_token: + description: >- + Pagination token for retrieving the next page. Empty if this is the last + page. Pass this value to page_token in the next request. + type: string + examples: + - eyJvZmZzZXQiOjIwfQ== + prev_page_token: + description: >- + Pagination token for retrieving the previous page. Empty if this is the + first page. Pass this value to page_token to go back. + type: string + examples: + - eyJvZmZzZXQiOjB9 + total_size: + description: >- + Total count of connected accounts matching the filter criteria across all + pages. Use for calculating pagination. + type: integer + format: int64 + examples: + - 100 diff --git a/openapi/components/schemas/connected_accountsOauthToken.yaml b/openapi/components/schemas/connected_accountsOauthToken.yaml new file mode 100644 index 000000000..2105aaffa --- /dev/null +++ b/openapi/components/schemas/connected_accountsOauthToken.yaml @@ -0,0 +1,34 @@ +type: object +title: OAuth 2.0 access and refresh tokens with scopes +properties: + access_token: + description: >- + OAuth access token for API requests. Typically short-lived and must be + refreshed after expiration. + type: string + examples: + - ya29.a0AfH6SMBx... + domain: + description: >- + Associated domain for workspace or organization-scoped OAuth connections + (e.g., Google Workspace domain). + type: string + examples: + - example.com + refresh_token: + description: >- + OAuth refresh token for obtaining new access tokens. Long-lived and used + to maintain persistent authorization. + type: string + examples: + - 1//0gHJxZ-Lb2... + scopes: + description: >- + List of granted OAuth scopes defining the permissions and access levels + for this connection. + type: array + items: + type: string + examples: + - - https://www.googleapis.com/auth/drive.readonly + - https://www.googleapis.com/auth/userinfo.email diff --git a/openapi/components/schemas/connected_accountsSearchConnectedAccountsResponse.yaml b/openapi/components/schemas/connected_accountsSearchConnectedAccountsResponse.yaml new file mode 100644 index 000000000..5362c7bb4 --- /dev/null +++ b/openapi/components/schemas/connected_accountsSearchConnectedAccountsResponse.yaml @@ -0,0 +1,26 @@ +type: object +properties: + connected_accounts: + description: >- + List of connected accounts matching the search query. Excludes sensitive + authorization details. + type: array + items: + type: object + $ref: ./connected_accountsConnectedAccountForList.yaml + next_page_token: + description: Pagination token for the next page. Empty if this is the last page. + type: string + examples: + - eyJvZmZzZXQiOjMwfQ== + prev_page_token: + description: Pagination token for the previous page. Empty if this is the first page. + type: string + examples: + - eyJvZmZzZXQiOjB9 + total_size: + description: Total count of accounts matching the search query across all pages. + type: integer + format: int64 + examples: + - 100 diff --git a/openapi/components/schemas/connected_accountsStaticAuth.yaml b/openapi/components/schemas/connected_accountsStaticAuth.yaml new file mode 100644 index 000000000..3034fa803 --- /dev/null +++ b/openapi/components/schemas/connected_accountsStaticAuth.yaml @@ -0,0 +1,11 @@ +type: object +title: Static authentication credentials for API keys, bearer tokens, or basic auth +properties: + details: + description: >- + Flexible JSON structure containing static credentials. Format varies by + connector type (API key, username/password, etc.). + type: object + examples: + - api_key: sk_live_... + api_secret: ... diff --git a/openapi/components/schemas/connected_accountsUpdateConnectedAccountRequest.yaml b/openapi/components/schemas/connected_accountsUpdateConnectedAccountRequest.yaml new file mode 100644 index 000000000..5b0968121 --- /dev/null +++ b/openapi/components/schemas/connected_accountsUpdateConnectedAccountRequest.yaml @@ -0,0 +1,43 @@ +type: object +properties: + connected_account: + description: Details of the connected account to update + $ref: ./v1connected_accountsUpdateConnectedAccount.yaml + examples: + - authorization_details: + oauth_token: + access_token: ... + refresh_token: ... + scopes: + - read + - write + authorization_type: OAUTH2 + connector: + description: >- + Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric + characters, spaces, hyphens, underscores, and colons are allowed. + type: string + examples: + - notion + id: + description: Unique identifier for the connected account to update + type: string + examples: + - ca_123 + identifier: + description: >- + The unique identifier for the connected account within the third-party + service (e.g., email address, user ID, workspace identifier). + type: string + examples: + - user@example.com + organization_id: + description: Organization ID for the connector + type: string + examples: + - org_121312434123312 + user_id: + description: User ID for the connector + type: string + examples: + - user_121312434123312 diff --git a/openapi/components/schemas/connected_accountsUpdateConnectedAccountResponse.yaml b/openapi/components/schemas/connected_accountsUpdateConnectedAccountResponse.yaml new file mode 100644 index 000000000..e309a403e --- /dev/null +++ b/openapi/components/schemas/connected_accountsUpdateConnectedAccountResponse.yaml @@ -0,0 +1,7 @@ +type: object +properties: + connected_account: + description: >- + The updated connected account with refreshed credentials, new token + expiry, and modified configuration settings. + $ref: ./connected_accountsConnectedAccount.yaml diff --git a/openapi/components/schemas/connected_accountsVerifyConnectedAccountUserRequest.yaml b/openapi/components/schemas/connected_accountsVerifyConnectedAccountUserRequest.yaml new file mode 100644 index 000000000..b193bdaf9 --- /dev/null +++ b/openapi/components/schemas/connected_accountsVerifyConnectedAccountUserRequest.yaml @@ -0,0 +1,17 @@ +type: object +required: + - auth_request_id + - identifier +properties: + auth_request_id: + description: >- + Auth request ID as base64url-encoded opaque token from the user verify + redirect URL query params + type: string + examples: + - QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY= + identifier: + description: Current logged in user's connected account identifier + type: string + examples: + - user@example.com diff --git a/openapi/components/schemas/connected_accountsVerifyConnectedAccountUserResponse.yaml b/openapi/components/schemas/connected_accountsVerifyConnectedAccountUserResponse.yaml new file mode 100644 index 000000000..bc71614be --- /dev/null +++ b/openapi/components/schemas/connected_accountsVerifyConnectedAccountUserResponse.yaml @@ -0,0 +1,7 @@ +type: object +properties: + post_user_verify_redirect_url: + description: URL to redirect the user to after successful verification + type: string + examples: + - https://env1.example.com/connect/success diff --git a/openapi/components/schemas/connectionsCodeChallengeType.yaml b/openapi/components/schemas/connectionsCodeChallengeType.yaml new file mode 100644 index 000000000..b6e390e55 --- /dev/null +++ b/openapi/components/schemas/connectionsCodeChallengeType.yaml @@ -0,0 +1,4 @@ +type: string +enum: + - NUMERIC + - ALPHANUMERIC diff --git a/openapi/components/schemas/connectionsConfigurationType.yaml b/openapi/components/schemas/connectionsConfigurationType.yaml new file mode 100644 index 000000000..49ed1e2e4 --- /dev/null +++ b/openapi/components/schemas/connectionsConfigurationType.yaml @@ -0,0 +1,4 @@ +type: string +enum: + - DISCOVERY + - MANUAL diff --git a/openapi/components/schemas/connectionsConnection.yaml b/openapi/components/schemas/connectionsConnection.yaml new file mode 100644 index 000000000..e0f6b74b5 --- /dev/null +++ b/openapi/components/schemas/connectionsConnection.yaml @@ -0,0 +1,128 @@ +type: object +properties: + attribute_mapping: + description: >- + Maps identity provider attributes to user profile fields. For example, + {'email': 'user.mail', 'name': 'user.displayName'}. + type: object + additionalProperties: + type: string + configuration_type: + description: >- + How the connection was configured: DISCOVERY (automatic configuration) or + MANUAL (administrator configured) + $ref: ./connectionsConfigurationType.yaml + examples: + - MANUAL + debug_enabled: + description: >- + Enables testing mode that allows non-HTTPS endpoints. Should only be + enabled in development environments, never in production. + type: boolean + examples: + - true + domains: + description: >- + Domain associated with this connection, used for domain-based + authentication flows. + type: array + items: + type: object + $ref: ./domainsDomain.yaml + examples: + - - name: example.com + enabled: + description: >- + Controls whether users can sign in using this connection. When false, the + connection exists but cannot be used for authentication. + type: boolean + examples: + - false + google_dwd_config: + description: >- + Configuration details for Google Domain-Wide Delegation. Present only when + type is GOOGLE_DWD. + $ref: ./connectionsGoogleDWDConfig.yaml + id: + description: >- + Unique identifier for this connection. Used in API calls to reference this + specific connection. + type: string + examples: + - conn_2123312131125533 + key_id: + description: >- + Alternative identifier for this connection, typically used in frontend + applications or URLs. + type: string + oauth_config: + description: >- + Configuration details for OAuth connections. Present only when type is + OAUTH. + $ref: ./connectionsOAuthConnectionConfig.yaml + oidc_config: + description: >- + Configuration details for OpenID Connect (OIDC) connections. Present only + when type is OIDC. + $ref: ./connectionsOIDCConnectionConfig.yaml + organization_id: + description: >- + Identifier of the organization that owns this connection. Connections are + typically scoped to a single organization. + type: string + examples: + - org_2123312131125533 + passwordless_config: + description: >- + Configuration details for Magic Link authentication. Present only when + type is MAGIC_LINK. + $ref: ./connectionsPasswordLessConfig.yaml + provider: + description: >- + Identity provider service that handles authentication (such as OKTA, + Google, Azure AD, or a custom provider) + $ref: ./connectionsConnectionProvider.yaml + examples: + - OKTA + provider_key: + description: Key ID of the identity provider service that handles authentication + type: string + examples: + - google + saml_config: + description: >- + Configuration details for SAML connections. Present only when type is + SAML. + $ref: ./connectionsSAMLConnectionConfigResponse.yaml + static_config: + description: >- + Static configuration for custom connections. Present only when type is + BASIC, BEARER, API_KEY, or custom. + $ref: ./connectionsStaticAuthConfig.yaml + status: + description: >- + Current configuration status of the connection. Possible values include + IN_PROGRESS, CONFIGURED, and ERROR. + $ref: ./connectionsConnectionStatus.yaml + readOnly: true + examples: + - IN_PROGRESS + test_connection_uri: + description: >- + URI that can be used to test this connection. Visit this URL to verify the + connection works correctly. + type: string + examples: + - https://auth.example.com/test-connection/conn_2123312131125533 + type: + description: >- + Authentication protocol used by this connection. Can be OIDC (OpenID + Connect), SAML, OAUTH, or MAGIC_LINK. + $ref: ./connectionsConnectionType.yaml + examples: + - OIDC + webauthn_config: + description: >- + Configuration details for WebAuthn (passkeys). Present only when type is + WEBAUTHN. + $ref: ./connectionsWebAuthConfiguration.yaml diff --git a/openapi/components/schemas/connectionsConnectionProvider.yaml b/openapi/components/schemas/connectionsConnectionProvider.yaml new file mode 100644 index 000000000..5f6b76ebc --- /dev/null +++ b/openapi/components/schemas/connectionsConnectionProvider.yaml @@ -0,0 +1,18 @@ +type: string +enum: + - OKTA + - GOOGLE + - MICROSOFT_AD + - AUTH0 + - ONELOGIN + - PING_IDENTITY + - JUMPCLOUD + - CUSTOM + - GITHUB + - GITLAB + - LINKEDIN + - SALESFORCE + - MICROSOFT + - IDP_SIMULATOR + - SCALEKIT + - ADFS diff --git a/openapi/components/schemas/connectionsConnectionStatus.yaml b/openapi/components/schemas/connectionsConnectionStatus.yaml new file mode 100644 index 000000000..bc55c7349 --- /dev/null +++ b/openapi/components/schemas/connectionsConnectionStatus.yaml @@ -0,0 +1,5 @@ +type: string +enum: + - DRAFT + - IN_PROGRESS + - COMPLETED diff --git a/openapi/components/schemas/connectionsConnectionType.yaml b/openapi/components/schemas/connectionsConnectionType.yaml new file mode 100644 index 000000000..b040b2009 --- /dev/null +++ b/openapi/components/schemas/connectionsConnectionType.yaml @@ -0,0 +1,14 @@ +type: string +enum: + - OIDC + - SAML + - PASSWORD + - OAUTH + - PASSWORDLESS + - BASIC + - BEARER + - API_KEY + - WEBAUTHN + - OAUTH_M2M + - TRELLO_OAUTH1 + - GOOGLE_DWD diff --git a/openapi/components/schemas/connectionsGetConnectionResponse.yaml b/openapi/components/schemas/connectionsGetConnectionResponse.yaml new file mode 100644 index 000000000..82104c7ea --- /dev/null +++ b/openapi/components/schemas/connectionsGetConnectionResponse.yaml @@ -0,0 +1,8 @@ +type: object +properties: + connection: + description: >- + Complete connection details including provider configuration, protocol + settings, status, and all metadata. Contains everything needed to + understand the connection's current state. + $ref: ./connectionsConnection.yaml diff --git a/openapi/components/schemas/connectionsGoogleDWDConfig.yaml b/openapi/components/schemas/connectionsGoogleDWDConfig.yaml new file mode 100644 index 000000000..466b0a7a4 --- /dev/null +++ b/openapi/components/schemas/connectionsGoogleDWDConfig.yaml @@ -0,0 +1,15 @@ +type: object +properties: + scopes: + description: OAuth 2.0 scopes to request. + type: array + items: + type: string + service_account_json: + description: >- + Google Cloud service account JSON key. Write-only: reads return a masked + value. + type: string + token_uri: + description: Google token endpoint. Defaults to https://oauth2.googleapis.com/token. + type: string diff --git a/openapi/components/schemas/connectionsIDPCertificate.yaml b/openapi/components/schemas/connectionsIDPCertificate.yaml new file mode 100644 index 000000000..768887e4c --- /dev/null +++ b/openapi/components/schemas/connectionsIDPCertificate.yaml @@ -0,0 +1,27 @@ +type: object +properties: + certificate: + description: IDP Certificate + type: string + create_time: + description: Certificate Creation Time + type: string + format: date-time + examples: + - '2021-09-01T00:00:00Z' + expiry_time: + description: Certificate Expiry Time + type: string + format: date-time + examples: + - '2021-09-01T00:00:00Z' + id: + description: Certificate ID + type: string + examples: + - cert_123123123123 + issuer: + description: Certificate Issuer + type: string + examples: + - https://youridp.com/service/saml diff --git a/openapi/components/schemas/connectionsListConnection.yaml b/openapi/components/schemas/connectionsListConnection.yaml new file mode 100644 index 000000000..8b1179d5c --- /dev/null +++ b/openapi/components/schemas/connectionsListConnection.yaml @@ -0,0 +1,58 @@ +type: object +properties: + domains: + description: List of domains configured with this connection + type: array + items: + type: string + examples: + - - yourapp.com + - yourworkspace.com + enabled: + description: Whether the connection is currently active for organization users + type: boolean + examples: + - false + id: + description: Unique identifier of the connection + type: string + examples: + - conn_2123312131125533 + key_id: + description: >- + Alternative identifier for this connection, typically used in frontend + applications or URLs + type: string + examples: + - conn_2123312131125533 + organization_id: + description: Unique identifier of the organization that owns this connection + type: string + examples: + - org_2123312131125533 + organization_name: + description: Name of the organization of the connection + type: string + examples: + - Your Organization + provider: + description: Identity provider type (e.g., OKTA, Google, Azure AD) + $ref: ./connectionsConnectionProvider.yaml + examples: + - CUSTOM + provider_key: + description: Key ID of the identity provider service that handles authentication + type: string + examples: + - google + status: + description: Current configuration status of the connection + $ref: ./connectionsConnectionStatus.yaml + readOnly: true + examples: + - IN_PROGRESS + type: + description: Authentication protocol used by the connection + $ref: ./connectionsConnectionType.yaml + examples: + - OIDC diff --git a/openapi/components/schemas/connectionsListConnectionsResponse.yaml b/openapi/components/schemas/connectionsListConnectionsResponse.yaml new file mode 100644 index 000000000..964d03297 --- /dev/null +++ b/openapi/components/schemas/connectionsListConnectionsResponse.yaml @@ -0,0 +1,8 @@ +type: object +properties: + connections: + description: List of connections matching the request criteria + type: array + items: + type: object + $ref: ./connectionsListConnection.yaml diff --git a/openapi/components/schemas/connectionsNameIdFormat.yaml b/openapi/components/schemas/connectionsNameIdFormat.yaml new file mode 100644 index 000000000..28a5fced7 --- /dev/null +++ b/openapi/components/schemas/connectionsNameIdFormat.yaml @@ -0,0 +1,6 @@ +type: string +enum: + - UNSPECIFIED + - EMAIL + - TRANSIENT + - PERSISTENT diff --git a/openapi/components/schemas/connectionsOAuthConnectionConfig.yaml b/openapi/components/schemas/connectionsOAuthConnectionConfig.yaml new file mode 100644 index 000000000..29340e03a --- /dev/null +++ b/openapi/components/schemas/connectionsOAuthConnectionConfig.yaml @@ -0,0 +1,106 @@ +type: object +properties: + access_type: + description: Access Type + type: string + examples: + - offline + app_name: + description: >- + Application name used by providers that require it as an authorize query + parameter (e.g., Trello's app_name). + type: string + examples: + - My Trello App + authorize_uri: + description: Authorize URI + type: string + examples: + - https://youridp.com/service/oauth/authorize + client_id: + description: Client ID + type: string + examples: + - oauth_client_id + client_secret: + description: Client Secret + type: string + examples: + - oauth_client_secret + custom_scope_name: + description: Custom Scope Name + type: string + examples: + - user_scope + is_cimd: + description: >- + Indicates whether this connection was registered using Client ID Metadata + Document (CIMD) instead of Dynamic Client Registration. + type: boolean + readOnly: true + examples: + - true + optional_scopes: + description: >- + Optional scopes configuration for identity providers that support or + require additional scopes to be sent in a custom field during + authentication requests. + $ref: ./connectionsOptionalScopes.yaml + pkce_enabled: + description: PKCE Enabled + type: boolean + examples: + - true + prompt: + description: Prompt for the user + type: string + examples: + - none + redirect_uri: + description: Redirect URI + type: string + examples: + - https://yourapp.com/service/oauth/redirect + scopes: + description: OIDC Scopes + type: array + items: + type: string + examples: + - - openid + - profile + sync_user_profile_on_login: + description: >- + Indicates whether user profiles should be synchronized with the identity + provider upon each log-in. + type: boolean + examples: + - true + tenant_id: + description: >- + Microsoft Entra tenant ID. Required when using a single-tenant or + multi-tenant app registered in Microsoft Entra. Leave empty to use the + common endpoint. + type: string + examples: + - xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + token_access_type: + description: Token Access Type + type: string + examples: + - offline + token_uri: + description: Token URI + type: string + examples: + - https://youridp.com/service/oauth/token + use_platform_creds: + description: Use Scalekit credentials + type: boolean + examples: + - true + user_info_uri: + description: User Info URI + type: string + examples: + - https://youridp.com/service/oauth/userinfo diff --git a/openapi/components/schemas/connectionsOIDCConnectionConfig.yaml b/openapi/components/schemas/connectionsOIDCConnectionConfig.yaml new file mode 100644 index 000000000..3b4a12ae8 --- /dev/null +++ b/openapi/components/schemas/connectionsOIDCConnectionConfig.yaml @@ -0,0 +1,94 @@ +type: object +properties: + authorize_uri: + description: Authorize URI + type: string + examples: + - https://youridp.com/service/oauth/authorize + backchannel_logout_redirect_uri: + description: backchannel logout redirect uri where idp sends logout_token + type: string + readOnly: true + examples: + - https://yourapp.com/sso/v1/oidc/conn_1234/backchannel-logout + client_id: + description: Client ID + type: string + examples: + - oauth_client_id + client_secret: + description: Client Secret + type: string + examples: + - oauth_client_secret + discovery_endpoint: + description: Discovery Endpoint + type: string + examples: + - https://youridp.com/service/oauth/.well-known/openid-configuration + idp_logout_required: + description: Enable IDP logout + type: boolean + examples: + - true + issuer: + description: Issuer URL + type: string + examples: + - https://youridp.com/service/oauth + jit_provisioning_with_sso_enabled: + description: Indicates if Just In Time user provisioning is enabled for the connection + type: boolean + examples: + - true + jwks_uri: + description: JWKS URI + type: string + examples: + - https://youridp.com/service/oauth/jwks + pkce_enabled: + description: PKCE Enabled + type: boolean + examples: + - true + post_logout_redirect_uri: + description: post logout redirect uri + type: string + readOnly: true + examples: + - https://yourapp.com/sso/v1/oidc/conn_1234/logout/callback + redirect_uri: + description: Redirect URI + type: string + examples: + - https://yourapp.com/sso/v1/oidc/conn_1234/callback + scopes: + description: OIDC Scopes + type: array + items: + $ref: ./connectionsOIDCScope.yaml + examples: + - - openid + - profile + sync_user_profile_on_login: + description: >- + Indicates whether user profiles should be synchronized with the identity + provider upon each log-in. + type: boolean + examples: + - true + token_auth_type: + description: Token Auth Type + $ref: ./connectionsTokenAuthType.yaml + examples: + - URL_PARAMS + token_uri: + description: Token URI + type: string + examples: + - https://youridp.com/service/oauth/token + user_info_uri: + description: User Info URI + type: string + examples: + - https://youridp.com/service/oauth/userinfo diff --git a/openapi/components/schemas/connectionsOIDCScope.yaml b/openapi/components/schemas/connectionsOIDCScope.yaml new file mode 100644 index 000000000..886f6120d --- /dev/null +++ b/openapi/components/schemas/connectionsOIDCScope.yaml @@ -0,0 +1,7 @@ +type: string +enum: + - openid + - profile + - email + - address + - phone diff --git a/openapi/components/schemas/connectionsOptionalScopes.yaml b/openapi/components/schemas/connectionsOptionalScopes.yaml new file mode 100644 index 000000000..cf8ea0f5a --- /dev/null +++ b/openapi/components/schemas/connectionsOptionalScopes.yaml @@ -0,0 +1,18 @@ +type: object +properties: + field_name: + description: >- + Name of the field in which scope should be sent in the authentication + request. This is required by some identity providers that expect scopes to + be sent in a custom field instead of the standard 'scope' parameter. + type: string + examples: + - optional_scope or bot_scope + scopes: + description: List of optional scopes that can be requested during authentication + type: array + items: + type: string + examples: + - - scope1 + - scope2 diff --git a/openapi/components/schemas/connectionsPasswordLessConfig.yaml b/openapi/components/schemas/connectionsPasswordLessConfig.yaml new file mode 100644 index 000000000..56fcb7f50 --- /dev/null +++ b/openapi/components/schemas/connectionsPasswordLessConfig.yaml @@ -0,0 +1,40 @@ +type: object +properties: + code_challenge_length: + description: Code Challenge Length + type: integer + format: int64 + examples: + - 6 + code_challenge_type: + description: Code Challenge Type + $ref: ./connectionsCodeChallengeType.yaml + examples: + - NUMERIC + enforce_same_browser_origin: + description: Enforce Same Browser Origin + type: boolean + examples: + - true + frequency: + description: Link Frequency + type: integer + format: int64 + examples: + - 1 + regenerate_passwordless_credentials_on_resend: + description: 'Regenerate the ' + type: boolean + examples: + - true + type: + description: Passwordless Type + $ref: ./connectionsPasswordlessType.yaml + examples: + - LINK + validity: + description: Link Validity in Seconds + type: integer + format: int64 + examples: + - 600 diff --git a/openapi/components/schemas/connectionsPasswordlessType.yaml b/openapi/components/schemas/connectionsPasswordlessType.yaml new file mode 100644 index 000000000..10fd39e86 --- /dev/null +++ b/openapi/components/schemas/connectionsPasswordlessType.yaml @@ -0,0 +1,5 @@ +type: string +enum: + - LINK + - OTP + - LINK_OTP diff --git a/openapi/components/schemas/connectionsRequestBinding.yaml b/openapi/components/schemas/connectionsRequestBinding.yaml new file mode 100644 index 000000000..52341f8b3 --- /dev/null +++ b/openapi/components/schemas/connectionsRequestBinding.yaml @@ -0,0 +1,4 @@ +type: string +enum: + - HTTP_POST + - HTTP_REDIRECT diff --git a/openapi/components/schemas/connectionsSAMLConnectionConfigResponse.yaml b/openapi/components/schemas/connectionsSAMLConnectionConfigResponse.yaml new file mode 100644 index 000000000..36617193f --- /dev/null +++ b/openapi/components/schemas/connectionsSAMLConnectionConfigResponse.yaml @@ -0,0 +1,121 @@ +type: object +properties: + allow_idp_initiated_login: + description: Allow IDP Initiated Login + type: boolean + examples: + - true + assertion_encrypted: + description: Assertion Encrypted + type: boolean + examples: + - true + certificate_id: + description: Certificate ID + type: string + examples: + - cer_35585423166144613 + default_redirect_uri: + description: Default Redirect URI + type: string + examples: + - https://yourapp.com/service/saml/redirect + force_authn: + description: Force Authn + type: boolean + examples: + - true + idp_certificates: + description: IDP Certificates + type: array + items: + type: object + $ref: ./connectionsIDPCertificate.yaml + idp_entity_id: + description: IDP Entity ID + type: string + examples: + - https://youridp.com/service/saml + idp_metadata_url: + description: IDP Metadata URL + type: string + examples: + - https://youridp.com/service/saml/metadata + idp_name_id_format: + description: IDP Name ID Format + $ref: ./connectionsNameIdFormat.yaml + examples: + - EMAIL + idp_slo_request_binding: + description: IDP SLO Request Binding + $ref: ./connectionsRequestBinding.yaml + examples: + - HTTP_POST + idp_slo_required: + description: Enable IDP logout + type: boolean + examples: + - true + idp_slo_url: + description: IDP SLO URL + type: string + examples: + - https://youridp.com/service/saml/slo + idp_sso_request_binding: + description: IDP SSO Request Binding + $ref: ./connectionsRequestBinding.yaml + examples: + - HTTP_POST + idp_sso_url: + description: IDP SSO URL + type: string + examples: + - https://youridp.com/service/saml/sso + jit_provisioning_with_sso_enabled: + description: Indicates if Just In Time user provisioning is enabled for the connection + type: boolean + examples: + - true + saml_signing_option: + description: SAML Signing Option + $ref: ./connectionsSAMLSigningOptions.yaml + examples: + - SAML_ONLY_RESPONSE_SIGNING + sp_assertion_url: + description: SP Assertion URL + type: string + examples: + - https://youridp.com/service/saml/assertion + sp_entity_id: + description: SP Entity ID + type: string + examples: + - https://yourapp.com/service/saml + sp_metadata_url: + description: SP Metadata URL + type: string + examples: + - https://youridp.com/service/saml/metadata + sp_slo_url: + description: Service Provider SLO url + type: string + readOnly: true + examples: + - https://yourapp.com/sso/v1/saml/conn_1234/slo/callback + sync_user_profile_on_login: + description: >- + Indicates whether user profiles should be synchronized with the identity + provider upon each log-in. + type: boolean + examples: + - true + ui_button_title: + description: UI Button Title + type: string + examples: + - Login with SSO + want_request_signed: + description: Want Request Signed + type: boolean + examples: + - true diff --git a/openapi/components/schemas/connectionsSAMLSigningOptions.yaml b/openapi/components/schemas/connectionsSAMLSigningOptions.yaml new file mode 100644 index 000000000..df65f1e2e --- /dev/null +++ b/openapi/components/schemas/connectionsSAMLSigningOptions.yaml @@ -0,0 +1,8 @@ +type: string +title: enums all +enum: + - NO_SIGNING + - SAML_ONLY_RESPONSE_SIGNING + - SAML_ONLY_ASSERTION_SIGNING + - SAML_RESPONSE_ASSERTION_SIGNING + - SAML_RESPONSE_OR_ASSERTION_SIGNING diff --git a/openapi/components/schemas/connectionsStaticAuthConfig.yaml b/openapi/components/schemas/connectionsStaticAuthConfig.yaml new file mode 100644 index 000000000..6b92c29f7 --- /dev/null +++ b/openapi/components/schemas/connectionsStaticAuthConfig.yaml @@ -0,0 +1,4 @@ +type: object +properties: + static_config: + type: object diff --git a/openapi/components/schemas/connectionsToggleConnectionResponse.yaml b/openapi/components/schemas/connectionsToggleConnectionResponse.yaml new file mode 100644 index 000000000..1c5a3439c --- /dev/null +++ b/openapi/components/schemas/connectionsToggleConnectionResponse.yaml @@ -0,0 +1,14 @@ +type: object +properties: + enabled: + description: >- + Current state of the connection after the operation. True means the + connection is now enabled and can be used for authentication. + type: boolean + examples: + - true + error_message: + description: Error message if the operation fails + type: string + examples: + - placeholder diff --git a/openapi/components/schemas/connectionsTokenAuthType.yaml b/openapi/components/schemas/connectionsTokenAuthType.yaml new file mode 100644 index 000000000..2d86a6827 --- /dev/null +++ b/openapi/components/schemas/connectionsTokenAuthType.yaml @@ -0,0 +1,4 @@ +type: string +enum: + - URL_PARAMS + - BASIC_AUTH diff --git a/openapi/components/schemas/connectionsWebAuthConfiguration.yaml b/openapi/components/schemas/connectionsWebAuthConfiguration.yaml new file mode 100644 index 000000000..5d3346615 --- /dev/null +++ b/openapi/components/schemas/connectionsWebAuthConfiguration.yaml @@ -0,0 +1,24 @@ +type: object +title: >- + WebAuthConfiguration defines WebAuthn (passkeys) configuration limited to RP + and Attestation +properties: + attestation: + $ref: ./WebAuthConfigurationAttestation.yaml + authenticator_selection: + $ref: ./WebAuthConfigurationAuthenticatorSelection.yaml + authenticators: + $ref: ./WebAuthConfigurationAuthenticators.yaml + enable_auto_registration: + description: Enable auto registration for WebAuthn + type: boolean + enable_conditional_login: + description: Allow autofill of passkeys in login page + type: boolean + rp: + $ref: ./WebAuthConfigurationRp.yaml + show_passkey_button: + description: Show passkey button on login screen + type: boolean + timeout: + $ref: ./WebAuthConfigurationTimeout.yaml diff --git a/openapi/components/schemas/directoriesAttributeMapping.yaml b/openapi/components/schemas/directoriesAttributeMapping.yaml new file mode 100644 index 000000000..af01ab018 --- /dev/null +++ b/openapi/components/schemas/directoriesAttributeMapping.yaml @@ -0,0 +1,6 @@ +type: object +properties: + key: + type: string + map_to: + type: string diff --git a/openapi/components/schemas/directoriesAttributeMappings.yaml b/openapi/components/schemas/directoriesAttributeMappings.yaml new file mode 100644 index 000000000..75e5932cd --- /dev/null +++ b/openapi/components/schemas/directoriesAttributeMappings.yaml @@ -0,0 +1,7 @@ +type: object +properties: + attributes: + type: array + items: + type: object + $ref: ./directoriesAttributeMapping.yaml diff --git a/openapi/components/schemas/directoriesDirectory.yaml b/openapi/components/schemas/directoriesDirectory.yaml new file mode 100644 index 000000000..ac0c14674 --- /dev/null +++ b/openapi/components/schemas/directoriesDirectory.yaml @@ -0,0 +1,103 @@ +type: object +properties: + attribute_mappings: + description: >- + Mappings between directory attributes and Scalekit user and group + attributes + $ref: ./directoriesAttributeMappings.yaml + directory_endpoint: + description: >- + The endpoint URL generated by Scalekit for synchronizing users and groups + from the Directory Provider + type: string + examples: + - https://yourapp.scalekit.com/api/v1/directoies/dir_123212312/scim/v2 + directory_provider: + description: Identity provider connected to this directory + $ref: ./directoriesDirectoryProvider.yaml + examples: + - OKTA + directory_type: + description: >- + Type of the directory, indicating the protocol or standard used for + synchronization + $ref: ./directoriesDirectoryType.yaml + examples: + - SCIM + email: + description: Email Id associated with Directory whose access will be used for polling + type: string + examples: + - john.doe@scalekit.cloud + enabled: + description: >- + Indicates whether the directory is currently enabled and actively + synchronizing users and groups + type: boolean + examples: + - true + groups_tracked: + description: It indicates if all groups are tracked or select groups are tracked + type: string + examples: + - ALL + id: + description: Unique identifier of the directory + type: string + examples: + - dir_121312434123312 + last_synced_at: + description: >- + Timestamp of the last successful synchronization of users and groups from + the Directory Provider + type: string + format: date-time + examples: + - '2024-10-01T00:00:00Z' + name: + description: >- + Name of the directory, typically representing the connected Directory + provider + type: string + examples: + - Azure AD + organization_id: + description: Unique identifier of the organization to which the directory belongs + type: string + examples: + - org_121312434123312 + role_assignments: + description: >- + Role assignments associated with the directory, defining group based role + assignments + $ref: ./directoriesRoleAssignments.yaml + secrets: + description: >- + List of secrets used for authenticating and synchronizing with the + Directory Provider + type: array + items: + type: object + $ref: ./directoriesSecret.yaml + stats: + description: >- + Statistics and metrics related to the directory, such as synchronization + status and error counts + $ref: ./directoriesStats.yaml + status: + description: Directory Status + type: string + examples: + - IN_PROGRESS + total_groups: + description: Total number of groups in the directory + type: integer + format: int32 + examples: + - 10 + total_users: + description: Total number of users in the directory + type: integer + format: int32 + examples: + - 10 diff --git a/openapi/components/schemas/directoriesDirectoryGroup.yaml b/openapi/components/schemas/directoriesDirectoryGroup.yaml new file mode 100644 index 000000000..687a2b52b --- /dev/null +++ b/openapi/components/schemas/directoriesDirectoryGroup.yaml @@ -0,0 +1,27 @@ +type: object +properties: + display_name: + description: Display Name + type: string + examples: + - Admins + group_detail: + description: Complete Group Details Payload + type: object + id: + description: Group ID + type: string + examples: + - dirgroup_121312434123312 + total_users: + description: Total Users in the Group + type: integer + format: int32 + examples: + - 10 + updated_at: + description: Updated At + type: string + format: date-time + examples: + - '2024-10-01T00:00:00Z' diff --git a/openapi/components/schemas/directoriesDirectoryProvider.yaml b/openapi/components/schemas/directoriesDirectoryProvider.yaml new file mode 100644 index 000000000..5681a39dc --- /dev/null +++ b/openapi/components/schemas/directoriesDirectoryProvider.yaml @@ -0,0 +1,9 @@ +type: string +enum: + - OKTA + - GOOGLE + - MICROSOFT_AD + - AUTH0 + - ONELOGIN + - JUMPCLOUD + - PING_IDENTITY diff --git a/openapi/components/schemas/directoriesDirectoryType.yaml b/openapi/components/schemas/directoriesDirectoryType.yaml new file mode 100644 index 000000000..fa5e0634b --- /dev/null +++ b/openapi/components/schemas/directoriesDirectoryType.yaml @@ -0,0 +1,5 @@ +type: string +enum: + - SCIM + - LDAP + - POLL diff --git a/openapi/components/schemas/directoriesDirectoryUser.yaml b/openapi/components/schemas/directoriesDirectoryUser.yaml new file mode 100644 index 000000000..a0784ce5a --- /dev/null +++ b/openapi/components/schemas/directoriesDirectoryUser.yaml @@ -0,0 +1,47 @@ +type: object +properties: + email: + description: Email + type: string + examples: + - johndoe + emails: + description: Emails + type: array + items: + type: string + family_name: + description: Last Name + type: string + examples: + - Doe + given_name: + description: First Name + type: string + examples: + - John + groups: + description: Groups + type: array + items: + type: object + $ref: ./directoriesDirectoryGroup.yaml + id: + description: User ID + type: string + examples: + - diruser_121312434123312 + preferred_username: + description: Preferred Username + type: string + examples: + - johndoe + updated_at: + description: Updated At + type: string + format: date-time + examples: + - '2024-10-01T00:00:00Z' + user_detail: + description: Complete User Details Payload + type: object diff --git a/openapi/components/schemas/directoriesGetDirectoryResponse.yaml b/openapi/components/schemas/directoriesGetDirectoryResponse.yaml new file mode 100644 index 000000000..7aab956a0 --- /dev/null +++ b/openapi/components/schemas/directoriesGetDirectoryResponse.yaml @@ -0,0 +1,5 @@ +type: object +properties: + directory: + description: Detailed information about the requested directory + $ref: ./directoriesDirectory.yaml diff --git a/openapi/components/schemas/directoriesListDirectoriesResponse.yaml b/openapi/components/schemas/directoriesListDirectoriesResponse.yaml new file mode 100644 index 000000000..cec72e21e --- /dev/null +++ b/openapi/components/schemas/directoriesListDirectoriesResponse.yaml @@ -0,0 +1,8 @@ +type: object +properties: + directories: + description: List of directories associated with the organization + type: array + items: + type: object + $ref: ./directoriesDirectory.yaml diff --git a/openapi/components/schemas/directoriesListDirectoryGroupsResponse.yaml b/openapi/components/schemas/directoriesListDirectoryGroupsResponse.yaml new file mode 100644 index 000000000..8d5e1266a --- /dev/null +++ b/openapi/components/schemas/directoriesListDirectoryGroupsResponse.yaml @@ -0,0 +1,24 @@ +type: object +properties: + groups: + description: List of directory groups retrieved from the specified directory + type: array + items: + type: object + $ref: ./directoriesDirectoryGroup.yaml + next_page_token: + description: >- + Token to retrieve the next page of results. Use this token in the + 'page_token' field of the next request + type: string + prev_page_token: + description: >- + Token to retrieve the previous page of results. Use this token in the + 'page_token' field of the next request + type: string + total_size: + description: >- + Total number of groups matching the request criteria, regardless of + pagination + type: integer + format: int64 diff --git a/openapi/components/schemas/directoriesListDirectoryUsersResponse.yaml b/openapi/components/schemas/directoriesListDirectoryUsersResponse.yaml new file mode 100644 index 000000000..8c5efab96 --- /dev/null +++ b/openapi/components/schemas/directoriesListDirectoryUsersResponse.yaml @@ -0,0 +1,24 @@ +type: object +properties: + next_page_token: + description: >- + Token for pagination. Use this token in the 'page_token' field of the next + request to fetch the subsequent page of users + type: string + prev_page_token: + description: >- + Token for pagination. Use this token in the 'page_token' field of the next + request to fetch the prior page of users + type: string + total_size: + description: >- + Total number of users available in the directory that match the request + criteria + type: integer + format: int64 + users: + description: List of directory users retrieved from the specified directory + type: array + items: + type: object + $ref: ./directoriesDirectoryUser.yaml diff --git a/openapi/components/schemas/directoriesRoleAssignment.yaml b/openapi/components/schemas/directoriesRoleAssignment.yaml new file mode 100644 index 000000000..79400b474 --- /dev/null +++ b/openapi/components/schemas/directoriesRoleAssignment.yaml @@ -0,0 +1,9 @@ +type: object +properties: + group_id: + description: group ID for the role mapping + type: string + examples: + - dirgroup_121312434123 + role_name: + type: string diff --git a/openapi/components/schemas/directoriesRoleAssignments.yaml b/openapi/components/schemas/directoriesRoleAssignments.yaml new file mode 100644 index 000000000..94af41d65 --- /dev/null +++ b/openapi/components/schemas/directoriesRoleAssignments.yaml @@ -0,0 +1,7 @@ +type: object +properties: + assignments: + type: array + items: + type: object + $ref: ./directoriesRoleAssignment.yaml diff --git a/openapi/components/schemas/directoriesSecret.yaml b/openapi/components/schemas/directoriesSecret.yaml new file mode 100644 index 000000000..a35aab6ac --- /dev/null +++ b/openapi/components/schemas/directoriesSecret.yaml @@ -0,0 +1,37 @@ +type: object +properties: + create_time: + description: Creation Time + type: string + format: date-time + examples: + - '2024-10-01T00:00:00Z' + directory_id: + description: Directory ID + type: string + examples: + - dir_12362474900684814 + expire_time: + description: Expiry Time + type: string + format: date-time + examples: + - '2025-10-01T00:00:00Z' + id: + type: string + last_used_time: + description: Last Used Time + type: string + format: date-time + examples: + - '2024-10-01T00:00:00Z' + secret_suffix: + description: Secret Suffix + type: string + examples: + - Nzg5 + status: + description: Secret Status + $ref: ./directoriesSecretStatus.yaml + examples: + - INACTIVE diff --git a/openapi/components/schemas/directoriesSecretStatus.yaml b/openapi/components/schemas/directoriesSecretStatus.yaml new file mode 100644 index 000000000..70679d3b0 --- /dev/null +++ b/openapi/components/schemas/directoriesSecretStatus.yaml @@ -0,0 +1,3 @@ +type: string +enum: + - INACTIVE diff --git a/openapi/components/schemas/directoriesStats.yaml b/openapi/components/schemas/directoriesStats.yaml new file mode 100644 index 000000000..14fb24211 --- /dev/null +++ b/openapi/components/schemas/directoriesStats.yaml @@ -0,0 +1,26 @@ +type: object +properties: + group_updated_at: + description: Max time of Group Updated At for Directory + type: string + format: date-time + examples: + - '2024-10-01T00:00:00Z' + total_groups: + description: Total Groups in the Directory + type: integer + format: int32 + examples: + - 10 + total_users: + description: Total Users in the Directory + type: integer + format: int32 + examples: + - 10 + user_updated_at: + description: Max time of User Updated At for Directory + type: string + format: date-time + examples: + - '2024-10-01T00:00:00Z' diff --git a/openapi/components/schemas/directoriesToggleDirectoryResponse.yaml b/openapi/components/schemas/directoriesToggleDirectoryResponse.yaml new file mode 100644 index 000000000..d4ecac396 --- /dev/null +++ b/openapi/components/schemas/directoriesToggleDirectoryResponse.yaml @@ -0,0 +1,19 @@ +type: object +properties: + enabled: + description: >- + Specifies the directory's state after the toggle operation. A value of + `true` indicates that the directory is enabled and actively synchronizing + users and groups. A value of `false` means the directory is disabled, + halting synchronization + type: boolean + examples: + - true + error_message: + description: >- + Contains a human-readable error message if the toggle operation + encountered an issue. If the operation was successful, this field will be + empty + type: string + examples: + - The directory is already enabled diff --git a/openapi/components/schemas/domainsCreateDomainResponse.yaml b/openapi/components/schemas/domainsCreateDomainResponse.yaml new file mode 100644 index 000000000..0e29e0d29 --- /dev/null +++ b/openapi/components/schemas/domainsCreateDomainResponse.yaml @@ -0,0 +1,7 @@ +type: object +properties: + domain: + description: >- + The newly created domain object with all configuration details and + system-generated identifiers. + $ref: ./domainsDomain.yaml diff --git a/openapi/components/schemas/domainsDomain.yaml b/openapi/components/schemas/domainsDomain.yaml new file mode 100644 index 000000000..87cd699e7 --- /dev/null +++ b/openapi/components/schemas/domainsDomain.yaml @@ -0,0 +1,67 @@ +type: object +properties: + create_time: + description: Timestamp when the domain was first created. + type: string + format: date-time + examples: + - '2025-09-01T12:14:43.100000Z' + domain: + description: >- + The business domain name that was configured for allowed email domain + functionality (e.g., company.com, subdomain.company.com). + type: string + examples: + - customerdomain.com + domain_type: + example: ORGANIZATION_DOMAIN + environment_id: + description: The environment ID where this domain is configured. + type: string + examples: + - env_58345499215790610 + id: + description: Scalekit-generated unique identifier for this domain record. + type: string + examples: + - dom_88351643129225005 + organization_id: + description: The organization to which the domain belongs. + type: string + examples: + - org_81667076086825451 + update_time: + description: Timestamp when the domain was last updated. + type: string + format: date-time + examples: + - '2025-09-01T12:14:43.110455Z' + verification_method: + description: >- + Method that determines how domain ownership is verified. + + - ADMIN: domain is marked verified without DNS validation, typically by an + admin. + + - DNS: domain must be verified by adding a TXT record to your DNS + configuration. + + - NOT_APPLICABLE: verification does not apply to this domain type. + $ref: ./domainsVerificationMethod.yaml + examples: + - ADMIN + verification_status: + description: >- + Verification status of the domain. + + - PENDING: DNS TXT record has not been validated yet. + + - VERIFIED: domain confirmed via DNS TXT record validation or admin + approval. + + - AUTO_VERIFIED: domain verified automatically without DNS changes. + + - FAILED: DNS TXT record was not validated within the verification window. + $ref: ./domainsVerificationStatus.yaml + examples: + - AUTO_VERIFIED diff --git a/openapi/components/schemas/domainsDomainType.yaml b/openapi/components/schemas/domainsDomainType.yaml new file mode 100644 index 000000000..4ec302d67 --- /dev/null +++ b/openapi/components/schemas/domainsDomainType.yaml @@ -0,0 +1,7 @@ +type: string +enum: + - ALLOWED_EMAIL_DOMAIN + - ORGANIZATION_DOMAIN +x-enum-varnames: + - ORGANIZATION_DOMAIN + - ALLOWED_EMAIL_DOMAIN diff --git a/openapi/components/schemas/domainsGetDomainResponse.yaml b/openapi/components/schemas/domainsGetDomainResponse.yaml new file mode 100644 index 000000000..34f90a034 --- /dev/null +++ b/openapi/components/schemas/domainsGetDomainResponse.yaml @@ -0,0 +1,7 @@ +type: object +properties: + domain: + description: >- + The requested domain object with complete details including domain type, + timestamps and configuration. + $ref: ./domainsDomain.yaml diff --git a/openapi/components/schemas/domainsListDomainResponse.yaml b/openapi/components/schemas/domainsListDomainResponse.yaml new file mode 100644 index 000000000..be1d72b65 --- /dev/null +++ b/openapi/components/schemas/domainsListDomainResponse.yaml @@ -0,0 +1,22 @@ +type: object +properties: + domains: + description: >- + Array of domain objects containing all domain details including + verification status and configuration. + type: array + items: + type: object + $ref: ./domainsDomain.yaml + page_number: + description: Current page number in the pagination sequence. + type: integer + format: int32 + examples: + - 1 + page_size: + description: Number of domains returned in this page. + type: integer + format: int32 + examples: + - 1 diff --git a/openapi/components/schemas/domainsVerificationMethod.yaml b/openapi/components/schemas/domainsVerificationMethod.yaml new file mode 100644 index 000000000..807f462dd --- /dev/null +++ b/openapi/components/schemas/domainsVerificationMethod.yaml @@ -0,0 +1,5 @@ +type: string +enum: + - ADMIN + - DNS + - NOT_APPLICABLE diff --git a/openapi/components/schemas/domainsVerificationStatus.yaml b/openapi/components/schemas/domainsVerificationStatus.yaml new file mode 100644 index 000000000..308b57497 --- /dev/null +++ b/openapi/components/schemas/domainsVerificationStatus.yaml @@ -0,0 +1,6 @@ +type: string +enum: + - PENDING + - VERIFIED + - FAILED + - AUTO_VERIFIED diff --git a/openapi/components/schemas/errdetailsDebugInfo.yaml b/openapi/components/schemas/errdetailsDebugInfo.yaml new file mode 100644 index 000000000..5b457fa8d --- /dev/null +++ b/openapi/components/schemas/errdetailsDebugInfo.yaml @@ -0,0 +1,11 @@ +description: Describes additional debugging info. +type: object +properties: + detail: + description: Additional debugging information provided by the server. + type: string + stack_entries: + description: The stack trace entries indicating where the error occurred. + type: array + items: + type: string diff --git a/openapi/components/schemas/errdetailsErrorInfo.yaml b/openapi/components/schemas/errdetailsErrorInfo.yaml new file mode 100644 index 000000000..21fa4d3a9 --- /dev/null +++ b/openapi/components/schemas/errdetailsErrorInfo.yaml @@ -0,0 +1,18 @@ +type: object +properties: + debug_info: + $ref: ./errdetailsDebugInfo.yaml + error_code: + type: string + help_info: + $ref: ./errdetailsHelpInfo.yaml + localized_message_info: + $ref: ./errdetailsLocalizedMessageInfo.yaml + request_info: + $ref: ./errdetailsRequestInfo.yaml + resource_info: + $ref: ./errdetailsResourceInfo.yaml + tool_error_info: + $ref: ./errdetailsToolErrorInfo.yaml + validation_error_info: + $ref: ./errdetailsValidationErrorInfo.yaml diff --git a/openapi/components/schemas/errdetailsHelpInfo.yaml b/openapi/components/schemas/errdetailsHelpInfo.yaml new file mode 100644 index 000000000..c96cdb3c9 --- /dev/null +++ b/openapi/components/schemas/errdetailsHelpInfo.yaml @@ -0,0 +1,13 @@ +description: |- + HelpInfo provides documentation links attached to an error response. + When present in ErrorInfo, clients should surface these links to help + developers resolve the error. For example, a missing required field error + may include a link to the relevant guide. +type: object +properties: + links: + description: One or more links relevant to resolving the error. + type: array + items: + type: object + $ref: ./HelpInfoLink.yaml diff --git a/openapi/components/schemas/errdetailsLocalizedMessageInfo.yaml b/openapi/components/schemas/errdetailsLocalizedMessageInfo.yaml new file mode 100644 index 000000000..e8682167b --- /dev/null +++ b/openapi/components/schemas/errdetailsLocalizedMessageInfo.yaml @@ -0,0 +1,6 @@ +type: object +properties: + locale: + type: string + message: + type: string diff --git a/openapi/components/schemas/errdetailsRequestInfo.yaml b/openapi/components/schemas/errdetailsRequestInfo.yaml new file mode 100644 index 000000000..bdd6fac5a --- /dev/null +++ b/openapi/components/schemas/errdetailsRequestInfo.yaml @@ -0,0 +1,17 @@ +description: |- + Contains metadata about the request that clients can attach when filing a bug + or providing other forms of feedback. +type: object +properties: + request_id: + description: >- + An opaque string that should only be interpreted by the service generating + + it. For example, it can be used to identify requests in the service's + logs. + type: string + serving_data: + description: |- + Any data that was used to serve this request. For example, an encrypted + stack trace that can be sent back to the service provider for debugging. + type: string diff --git a/openapi/components/schemas/errdetailsResourceInfo.yaml b/openapi/components/schemas/errdetailsResourceInfo.yaml new file mode 100644 index 000000000..ffa4af94f --- /dev/null +++ b/openapi/components/schemas/errdetailsResourceInfo.yaml @@ -0,0 +1,20 @@ +description: Describes the resource that is being accessed. +type: object +properties: + description: + description: |- + Describes what error is encountered when accessing this resource. + For example, updating a cloud project may require the `writer` permission + on the developer console project. + type: string + owner: + type: string + required_permissions: + description: The required permissions needed to access the resource. + type: array + items: + type: string + resource_name: + type: string + user: + type: string diff --git a/openapi/components/schemas/errdetailsToolErrorInfo.yaml b/openapi/components/schemas/errdetailsToolErrorInfo.yaml new file mode 100644 index 000000000..7ed62c888 --- /dev/null +++ b/openapi/components/schemas/errdetailsToolErrorInfo.yaml @@ -0,0 +1,8 @@ +type: object +properties: + execution_id: + type: string + tool_error_code: + type: string + tool_error_message: + type: string diff --git a/openapi/components/schemas/errdetailsValidationErrorInfo.yaml b/openapi/components/schemas/errdetailsValidationErrorInfo.yaml new file mode 100644 index 000000000..e2f50ca2c --- /dev/null +++ b/openapi/components/schemas/errdetailsValidationErrorInfo.yaml @@ -0,0 +1,11 @@ +description: |- + Describes violations in a client request. This error type focuses on the + syntactic aspects of the request. +type: object +properties: + field_violations: + description: Describes all violations in a client request. + type: array + items: + type: object + $ref: ./ValidationErrorInfoFieldViolation.yaml diff --git a/openapi/components/schemas/organizationsCreateOrganizationResponse.yaml b/openapi/components/schemas/organizationsCreateOrganizationResponse.yaml new file mode 100644 index 000000000..89a6d5864 --- /dev/null +++ b/openapi/components/schemas/organizationsCreateOrganizationResponse.yaml @@ -0,0 +1,5 @@ +type: object +properties: + organization: + description: The newly created organization containing its ID, settings, and metadata + $ref: ./organizationsOrganization.yaml diff --git a/openapi/components/schemas/organizationsFeature.yaml b/openapi/components/schemas/organizationsFeature.yaml new file mode 100644 index 000000000..3fef4daa8 --- /dev/null +++ b/openapi/components/schemas/organizationsFeature.yaml @@ -0,0 +1,10 @@ +description: |- + - dir_sync: Enables directory synchronization configuration in the portal + - sso: Enables Single Sign-On (SSO) configuration in the portal +type: string +title: >- + Feature represents the available features that can be enabled for an + organization's portal link +enum: + - dir_sync + - sso diff --git a/openapi/components/schemas/organizationsGeneratePortalLinkResponse.yaml b/openapi/components/schemas/organizationsGeneratePortalLinkResponse.yaml new file mode 100644 index 000000000..bfc09d41f --- /dev/null +++ b/openapi/components/schemas/organizationsGeneratePortalLinkResponse.yaml @@ -0,0 +1,8 @@ +type: object +properties: + link: + description: >- + Contains the generated admin portal link details. The link URL can be + shared with organization administrators to set up: Single Sign-On (SSO) + authentication and directory synchronization + $ref: ./organizationsLink.yaml diff --git a/openapi/components/schemas/organizationsGetOrganizationResponse.yaml b/openapi/components/schemas/organizationsGetOrganizationResponse.yaml new file mode 100644 index 000000000..716b7b28c --- /dev/null +++ b/openapi/components/schemas/organizationsGetOrganizationResponse.yaml @@ -0,0 +1,5 @@ +type: object +properties: + organization: + description: The newly created organization + $ref: ./organizationsOrganization.yaml diff --git a/openapi/components/schemas/organizationsGetOrganizationSessionPolicyResponse.yaml b/openapi/components/schemas/organizationsGetOrganizationSessionPolicyResponse.yaml new file mode 100644 index 000000000..51c07a047 --- /dev/null +++ b/openapi/components/schemas/organizationsGetOrganizationSessionPolicyResponse.yaml @@ -0,0 +1,5 @@ +type: object +properties: + policy: + description: The session policy for the organization. + $ref: ./organizationsOrganizationSessionPolicySettings.yaml diff --git a/openapi/components/schemas/organizationsLink.yaml b/openapi/components/schemas/organizationsLink.yaml new file mode 100644 index 000000000..40b068ab6 --- /dev/null +++ b/openapi/components/schemas/organizationsLink.yaml @@ -0,0 +1,20 @@ +type: object +properties: + expire_time: + description: Expiry time of the link. The link is valid for 1 minute. + type: string + format: date-time + examples: + - '2024-02-06T14:48:00Z' + id: + description: Unique Identifier for the link + type: string + examples: + - lnk_123123123123123 + location: + description: >- + Location of the link. This is the URL that can be used to access the Admin + portal. The link is valid for 1 minute + type: string + examples: + - https://scalekit.com/portal/lnk_123123123123123 diff --git a/openapi/components/schemas/organizationsListOrganizationsResponse.yaml b/openapi/components/schemas/organizationsListOrganizationsResponse.yaml new file mode 100644 index 000000000..dffb4b426 --- /dev/null +++ b/openapi/components/schemas/organizationsListOrganizationsResponse.yaml @@ -0,0 +1,28 @@ +type: object +properties: + next_page_token: + description: >- + Pagination token for the next page of results. Use this token to fetch the + next page. + type: string + examples: + - + organizations: + description: List of organization objects + type: array + items: + type: object + $ref: ./organizationsOrganization.yaml + prev_page_token: + description: >- + Pagination token for the previous page of results. Use this token to fetch + the previous page. + type: string + examples: + - + total_size: + description: Total number of organizations in the environment. + type: integer + format: int64 + examples: + - 30 diff --git a/openapi/components/schemas/organizationsOrganization.yaml b/openapi/components/schemas/organizationsOrganization.yaml new file mode 100644 index 000000000..a4b85a67c --- /dev/null +++ b/openapi/components/schemas/organizationsOrganization.yaml @@ -0,0 +1,77 @@ +type: object +required: + - create_time +properties: + create_time: + description: Timestamp when the organization was created + type: string + format: date-time + title: Created Time + examples: + - '2025-02-15T06:23:44.560000Z' + display_name: + description: Name of the organization. Must be between 1 and 200 characters + type: string + title: Name of the org to be used in display + examples: + - Megasoft + external_id: + description: >- + Your application's unique identifier for this organization, used to link + Scalekit with your system. + type: string + title: >- + External Id is useful to store a unique identifier for a given Org that. + The unique Identifier can be the id of your tenant / org in your SaaSApp + examples: + - my_unique_id + id: + description: >- + Unique scalekit-generated identifier that uniquely references an + organization + type: string + title: Id + examples: + - org_59615193906282635 + logo_url: + description: >- + HTTPS URL of the organization's logo image. Maximum 2048 characters. Must + use the https scheme. + type: string + format: uri + maxLength: 2048 + pattern: ^https:// + examples: + - https://cdn.example.com/acme-logo.png + metadata: + description: Key value pairs extension attributes. + type: object + additionalProperties: + type: string + region_code: + description: Geographic region code for the organization. Currently limited to US. + title: Optional regioncode + $ref: ./commonsRegionCode.yaml + examples: + - US + settings: + title: Organization Settings + $ref: ./organizationsOrganizationSettings.yaml + slug: + description: >- + DNS-safe slug for dynamic redirect URI resolution. Must be 1-63 chars, + lowercase alphanumeric and hyphens, must start and end with an + alphanumeric character. Unique per environment. + type: string + maxLength: 63 + minLength: 1 + pattern: ^[a-z0-9]([a-z0-9]|-[a-z0-9])*$ + examples: + - acme + update_time: + description: Timestamp when the organization was last updated + type: string + format: date-time + title: Updated time + examples: + - '2025-02-15T06:23:44.560000Z' diff --git a/openapi/components/schemas/organizationsOrganizationSessionPolicySettings.yaml b/openapi/components/schemas/organizationsOrganizationSessionPolicySettings.yaml new file mode 100644 index 000000000..48489b26b --- /dev/null +++ b/openapi/components/schemas/organizationsOrganizationSessionPolicySettings.yaml @@ -0,0 +1,49 @@ +type: object +properties: + absolute_session_timeout: + description: >- + The absolute session timeout value. The unit is specified by + absolute_session_timeout_unit. Omitted when policy_source is + 'environment'. + type: integer + format: int32 + examples: + - 360 + absolute_session_timeout_unit: + description: >- + Unit for absolute_session_timeout. Accepted values: 'minutes', 'hours', + 'days'. Responses always return 'minutes'. + $ref: ./commonsTimeUnit.yaml + examples: + - minutes + idle_session_timeout: + description: >- + The idle session timeout value. The unit is specified by + idle_session_timeout_unit. Omitted when idle_session_timeout_enabled is + false or policy_source is 'environment'. + type: integer + format: int32 + examples: + - 84 + idle_session_timeout_enabled: + description: >- + Whether idle session timeout is enabled for this organization. Omitted + when policy_source is 'environment'. + type: boolean + examples: + - true + idle_session_timeout_unit: + description: >- + Unit for idle_session_timeout. Accepted values: 'minutes', 'hours', + 'days'. Responses always return 'minutes'. + $ref: ./commonsTimeUnit.yaml + examples: + - minutes + policy_source: + description: >- + Policy source. 'APPLICATION' means the organization inherits the + application-level session policy. 'CUSTOM' means organization-specific + timeout values are active. + $ref: ./organizationsSessionPolicyType.yaml + examples: + - CUSTOM diff --git a/openapi/components/schemas/organizationsOrganizationSettings.yaml b/openapi/components/schemas/organizationsOrganizationSettings.yaml new file mode 100644 index 000000000..3f654d798 --- /dev/null +++ b/openapi/components/schemas/organizationsOrganizationSettings.yaml @@ -0,0 +1,25 @@ +description: >- + Configuration options that control organization-level features and + capabilities +type: object +title: Organization Settings +properties: + features: + description: >- + List of feature toggles that control organization capabilities such as SSO + authentication and directory synchronization + type: array + items: + type: object + $ref: ./organizationsOrganizationSettingsFeature.yaml + examples: + - - enabled: true + name: sso + - enabled: false + name: directory_sync +examples: + - features: + - enabled: true + name: sso + - enabled: false + name: directory_sync diff --git a/openapi/components/schemas/organizationsOrganizationSettingsFeature.yaml b/openapi/components/schemas/organizationsOrganizationSettingsFeature.yaml new file mode 100644 index 000000000..15a9d41f4 --- /dev/null +++ b/openapi/components/schemas/organizationsOrganizationSettingsFeature.yaml @@ -0,0 +1,23 @@ +description: Controls the activation state of a specific organization feature +type: object +title: Organization Feature Toggle +required: + - name + - enabled +properties: + enabled: + description: >- + Whether the feature is enabled (true) or disabled (false) for this + organization + type: boolean + examples: + - true + name: + description: >- + Feature identifier. Supported values include: "sso" (Single Sign-On), + "directory_sync" (Directory Synchronization), "domain_verification" + (Domain Verification), "session_policy" (Organization-level session policy + override) + type: string + examples: + - sso diff --git a/openapi/components/schemas/organizationsOrganizationUserManagementSettings.yaml b/openapi/components/schemas/organizationsOrganizationUserManagementSettings.yaml new file mode 100644 index 000000000..9cb4326f9 --- /dev/null +++ b/openapi/components/schemas/organizationsOrganizationUserManagementSettings.yaml @@ -0,0 +1,12 @@ +type: object +properties: + max_allowed_users: + description: >- + Maximum number of users allowed in the organization. When nil (not set), + there feature is not enabled. When explicitly set to zero, it also means + no limit. When set to a positive integer, it enforces the maximum user + limit. + type: integer + format: int32 + examples: + - 100 diff --git a/openapi/components/schemas/organizationsSessionPolicyType.yaml b/openapi/components/schemas/organizationsSessionPolicyType.yaml new file mode 100644 index 000000000..3acf10c72 --- /dev/null +++ b/openapi/components/schemas/organizationsSessionPolicyType.yaml @@ -0,0 +1,4 @@ +type: string +enum: + - APPLICATION + - CUSTOM diff --git a/openapi/components/schemas/organizationsUpdateOrganizationResponse.yaml b/openapi/components/schemas/organizationsUpdateOrganizationResponse.yaml new file mode 100644 index 000000000..654a97897 --- /dev/null +++ b/openapi/components/schemas/organizationsUpdateOrganizationResponse.yaml @@ -0,0 +1,5 @@ +type: object +properties: + organization: + description: Updated organization details + $ref: ./organizationsOrganization.yaml diff --git a/openapi/components/schemas/organizationsUpdateOrganizationSessionPolicyResponse.yaml b/openapi/components/schemas/organizationsUpdateOrganizationSessionPolicyResponse.yaml new file mode 100644 index 000000000..451a0a393 --- /dev/null +++ b/openapi/components/schemas/organizationsUpdateOrganizationSessionPolicyResponse.yaml @@ -0,0 +1,5 @@ +type: object +properties: + policy: + description: The updated session policy for the organization. + $ref: ./organizationsOrganizationSessionPolicySettings.yaml diff --git a/openapi/components/schemas/organizationsUpsertUserManagementSettingsResponse.yaml b/openapi/components/schemas/organizationsUpsertUserManagementSettingsResponse.yaml new file mode 100644 index 000000000..13b1cb0ef --- /dev/null +++ b/openapi/components/schemas/organizationsUpsertUserManagementSettingsResponse.yaml @@ -0,0 +1,5 @@ +type: object +properties: + settings: + description: The updated setting. + $ref: ./organizationsOrganizationUserManagementSettings.yaml diff --git a/openapi/components/schemas/passwordlessResendPasswordlessRequest.yaml b/openapi/components/schemas/passwordlessResendPasswordlessRequest.yaml new file mode 100644 index 000000000..0e8ba2aab --- /dev/null +++ b/openapi/components/schemas/passwordlessResendPasswordlessRequest.yaml @@ -0,0 +1,10 @@ +type: object +properties: + auth_request_id: + description: >- + The authentication request identifier from the original send passwordless + email request. Use this to resend the Verification Code (OTP) or Magic + Link to the same email address. + type: string + examples: + - h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ diff --git a/openapi/components/schemas/passwordlessSendPasswordlessRequest.yaml b/openapi/components/schemas/passwordlessSendPasswordlessRequest.yaml new file mode 100644 index 000000000..1b71feb2d --- /dev/null +++ b/openapi/components/schemas/passwordlessSendPasswordlessRequest.yaml @@ -0,0 +1,65 @@ +type: object +properties: + email: + description: >- + Email address where the passwordless authentication credentials will be + sent. Must be a valid email format. + type: string + examples: + - john.doe@example.com + expires_in: + description: >- + Time in seconds until the passwordless authentication expires. If not + specified, defaults to 300 seconds (5 minutes) + type: integer + format: int64 + examples: + - 300 + magiclink_auth_uri: + description: >- + Your application's callback URL where users will be redirected after + clicking the magic link in their email. The link token will be appended as + a query parameter as link_token + type: string + examples: + - https://yourapp.com/auth/passwordless/callback + state: + description: >- + Custom state parameter that will be returned unchanged in the verification + response. Use this to maintain application state between the + authentication request and callback, such as the intended destination + after login + type: string + examples: + - d62ivasry29lso + template: + description: >- + Specifies the authentication intent for the passwordless request. Use + SIGNIN for existing users or SIGNUP for new user registration. This + affects the email template and user experience flow. + $ref: ./passwordlessTemplateType.yaml + examples: + - SIGNIN + template_variables: + description: >- + A set of key-value pairs to personalize the email template. + + + * You may include up to 30 key-value pairs. + + * The following variable names are reserved by the system and cannot be + supplied: `otp`, `expiry_time_relative`, `link`, `expire_time`, + `expiry_time`. + + * Every variable referenced in your email template must be included as a + key-value pair. + + + Use these variables to insert custom information, such as a team name, URL + or the user's employee ID. All variables are interpolated before the email + is sent, regardless of the email provider. + type: object + additionalProperties: + type: string + examples: + - custom_variable_key: custom_variable_value diff --git a/openapi/components/schemas/passwordlessSendPasswordlessResponse.yaml b/openapi/components/schemas/passwordlessSendPasswordlessResponse.yaml new file mode 100644 index 000000000..60c2446bd --- /dev/null +++ b/openapi/components/schemas/passwordlessSendPasswordlessResponse.yaml @@ -0,0 +1,37 @@ +type: object +properties: + auth_request_id: + description: >- + Unique identifier for this passwordless authentication request. Use this + ID to resend emails. + type: string + readOnly: true + examples: + - h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ + expires_at: + description: >- + Unix timestamp (seconds since epoch) when the passwordless authentication + will expire. After this time, the OTP or magic link will no longer be + valid. + type: string + format: int64 + readOnly: true + examples: + - 1748696575 + expires_in: + description: >- + Number of seconds from now until the passwordless authentication expires. + This is a convenience field calculated from the expires_at timestamp. + type: integer + format: int64 + readOnly: true + examples: + - 300 + passwordless_type: + description: >- + Type of passwordless authentication that was sent via email. OTP sends a + numeric code, LINK sends a clickable magic link, and LINK_OTP provides + both options for user convenience. + $ref: ./authpasswordlessPasswordlessType.yaml + examples: + - OTP diff --git a/openapi/components/schemas/passwordlessTemplateType.yaml b/openapi/components/schemas/passwordlessTemplateType.yaml new file mode 100644 index 000000000..47bce8b11 --- /dev/null +++ b/openapi/components/schemas/passwordlessTemplateType.yaml @@ -0,0 +1,4 @@ +type: string +enum: + - SIGNIN + - SIGNUP diff --git a/openapi/components/schemas/passwordlessVerifyPasswordLessRequest.yaml b/openapi/components/schemas/passwordlessVerifyPasswordLessRequest.yaml new file mode 100644 index 000000000..fd6686b48 --- /dev/null +++ b/openapi/components/schemas/passwordlessVerifyPasswordLessRequest.yaml @@ -0,0 +1,25 @@ +type: object +properties: + auth_request_id: + description: >- + The authentication request identifier returned from the send passwordless + email endpoint. Required when verifying OTP codes to link the verification + with the original request. + type: string + examples: + - h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ + code: + description: >- + The Verification Code (OTP) received via email. This is typically a + 6-digit numeric code that users enter manually to verify their identity. + type: string + examples: + - '123456' + link_token: + description: >- + The unique token from the magic link URL received via email. Extract this + token when users click the magic link and are redirected to your + application to later verify the user. + type: string + examples: + - afe9d61c-d80d-4020-a8ee-61765ab71cb3 diff --git a/openapi/components/schemas/passwordlessVerifyPasswordLessResponse.yaml b/openapi/components/schemas/passwordlessVerifyPasswordLessResponse.yaml new file mode 100644 index 000000000..07dfde42d --- /dev/null +++ b/openapi/components/schemas/passwordlessVerifyPasswordLessResponse.yaml @@ -0,0 +1,33 @@ +type: object +properties: + email: + description: >- + Email address of the successfully authenticated user. This confirms which + email account was verified through the passwordless flow. + type: string + readOnly: true + examples: + - john.doe@example.com + passwordless_type: + description: >- + The type of passwordless authentication that was successfully verified, + confirming which method the user completed. + $ref: ./authpasswordlessPasswordlessType.yaml + examples: + - OTP + state: + description: >- + The custom state parameter that was provided in the original + authentication request, returned unchanged. Use this to restore your + application's context after authentication. + type: string + readOnly: true + examples: + - kdt7yiag28t341fr1 + template: + description: >- + Specifies which email template to choose. For User Signin choose SIGNIN + and for User Signup use SIGNUP + $ref: ./passwordlessTemplateType.yaml + examples: + - SIGNIN diff --git a/openapi/components/schemas/protobufNullValue.yaml b/openapi/components/schemas/protobufNullValue.yaml new file mode 100644 index 000000000..12bf801c2 --- /dev/null +++ b/openapi/components/schemas/protobufNullValue.yaml @@ -0,0 +1,6 @@ +description: |- + `NullValue` is a singleton enumeration to represent the null value for the + `Value` type union. + + The JSON representation for `NullValue` is JSON `null`. +type: string diff --git a/openapi/components/schemas/rolesAddPermissionsToRoleResponse.yaml b/openapi/components/schemas/rolesAddPermissionsToRoleResponse.yaml new file mode 100644 index 000000000..e8cf21239 --- /dev/null +++ b/openapi/components/schemas/rolesAddPermissionsToRoleResponse.yaml @@ -0,0 +1,8 @@ +type: object +properties: + permissions: + description: List of all permissions belonging to the role after addition + type: array + items: + type: object + $ref: ./rolesPermission.yaml diff --git a/openapi/components/schemas/rolesCreateOrganizationRoleResponse.yaml b/openapi/components/schemas/rolesCreateOrganizationRoleResponse.yaml new file mode 100644 index 000000000..5f89b49de --- /dev/null +++ b/openapi/components/schemas/rolesCreateOrganizationRoleResponse.yaml @@ -0,0 +1,4 @@ +type: object +properties: + role: + $ref: ./v1rolesRole.yaml diff --git a/openapi/components/schemas/rolesCreatePermissionResponse.yaml b/openapi/components/schemas/rolesCreatePermissionResponse.yaml new file mode 100644 index 000000000..bf007adee --- /dev/null +++ b/openapi/components/schemas/rolesCreatePermissionResponse.yaml @@ -0,0 +1,4 @@ +type: object +properties: + permission: + $ref: ./rolesPermission.yaml diff --git a/openapi/components/schemas/rolesCreateRoleResponse.yaml b/openapi/components/schemas/rolesCreateRoleResponse.yaml new file mode 100644 index 000000000..5090d09c3 --- /dev/null +++ b/openapi/components/schemas/rolesCreateRoleResponse.yaml @@ -0,0 +1,12 @@ +type: object +properties: + role: + description: >- + The created role object with system-generated ID and all configuration + details. + $ref: ./v1rolesRole.yaml + examples: + - description: Can edit content + display_name: Content Editor + id: role_1234abcd5678efgh + name: content_editor diff --git a/openapi/components/schemas/rolesGetOrganizationRoleResponse.yaml b/openapi/components/schemas/rolesGetOrganizationRoleResponse.yaml new file mode 100644 index 000000000..5f89b49de --- /dev/null +++ b/openapi/components/schemas/rolesGetOrganizationRoleResponse.yaml @@ -0,0 +1,4 @@ +type: object +properties: + role: + $ref: ./v1rolesRole.yaml diff --git a/openapi/components/schemas/rolesGetPermissionResponse.yaml b/openapi/components/schemas/rolesGetPermissionResponse.yaml new file mode 100644 index 000000000..bf007adee --- /dev/null +++ b/openapi/components/schemas/rolesGetPermissionResponse.yaml @@ -0,0 +1,4 @@ +type: object +properties: + permission: + $ref: ./rolesPermission.yaml diff --git a/openapi/components/schemas/rolesGetRoleResponse.yaml b/openapi/components/schemas/rolesGetRoleResponse.yaml new file mode 100644 index 000000000..69ae0f32d --- /dev/null +++ b/openapi/components/schemas/rolesGetRoleResponse.yaml @@ -0,0 +1,14 @@ +type: object +properties: + role: + description: >- + The complete role object with all metadata, permissions, and inheritance + details. + $ref: ./v1rolesRole.yaml + examples: + - dependent_roles_count: 2 + display_name: Content Editor + id: role_1234abcd5678efgh + name: content_editor + permissions: + - name: read:content diff --git a/openapi/components/schemas/rolesGetRoleUsersCountResponse.yaml b/openapi/components/schemas/rolesGetRoleUsersCountResponse.yaml new file mode 100644 index 000000000..23baf7b8d --- /dev/null +++ b/openapi/components/schemas/rolesGetRoleUsersCountResponse.yaml @@ -0,0 +1,8 @@ +type: object +properties: + count: + description: Number of users associated with the role + type: string + format: int64 + examples: + - 10 diff --git a/openapi/components/schemas/rolesListDependentRolesResponse.yaml b/openapi/components/schemas/rolesListDependentRolesResponse.yaml new file mode 100644 index 000000000..47e3ff77d --- /dev/null +++ b/openapi/components/schemas/rolesListDependentRolesResponse.yaml @@ -0,0 +1,8 @@ +type: object +properties: + roles: + description: List of dependent roles + type: array + items: + type: object + $ref: ./v1rolesRole.yaml diff --git a/openapi/components/schemas/rolesListEffectiveRolePermissionsResponse.yaml b/openapi/components/schemas/rolesListEffectiveRolePermissionsResponse.yaml new file mode 100644 index 000000000..6df5934be --- /dev/null +++ b/openapi/components/schemas/rolesListEffectiveRolePermissionsResponse.yaml @@ -0,0 +1,10 @@ +type: object +properties: + permissions: + description: >- + List of all effective permissions including those inherited from base + roles + type: array + items: + type: object + $ref: ./rolesPermission.yaml diff --git a/openapi/components/schemas/rolesListOrganizationRolesResponse.yaml b/openapi/components/schemas/rolesListOrganizationRolesResponse.yaml new file mode 100644 index 000000000..24f4f8e3a --- /dev/null +++ b/openapi/components/schemas/rolesListOrganizationRolesResponse.yaml @@ -0,0 +1,8 @@ +type: object +properties: + roles: + description: List of roles objects + type: array + items: + type: object + $ref: ./v1rolesRole.yaml diff --git a/openapi/components/schemas/rolesListPermissionsResponse.yaml b/openapi/components/schemas/rolesListPermissionsResponse.yaml new file mode 100644 index 000000000..26d583aed --- /dev/null +++ b/openapi/components/schemas/rolesListPermissionsResponse.yaml @@ -0,0 +1,23 @@ +type: object +properties: + next_page_token: + description: Token to retrieve next page of results + type: string + examples: + - token_def456 + permissions: + type: array + items: + type: object + $ref: ./rolesPermission.yaml + prev_page_token: + description: Token to retrieve previous page of results + type: string + examples: + - token_def456 + total_size: + description: Total number of permissions available + type: integer + format: int64 + examples: + - 150 diff --git a/openapi/components/schemas/rolesListRolePermissionsResponse.yaml b/openapi/components/schemas/rolesListRolePermissionsResponse.yaml new file mode 100644 index 000000000..dd5be2999 --- /dev/null +++ b/openapi/components/schemas/rolesListRolePermissionsResponse.yaml @@ -0,0 +1,8 @@ +type: object +properties: + permissions: + description: List of permissions directly assigned to the role + type: array + items: + type: object + $ref: ./rolesPermission.yaml diff --git a/openapi/components/schemas/rolesListRolesResponse.yaml b/openapi/components/schemas/rolesListRolesResponse.yaml new file mode 100644 index 000000000..88cf1ed1b --- /dev/null +++ b/openapi/components/schemas/rolesListRolesResponse.yaml @@ -0,0 +1,17 @@ +type: object +properties: + roles: + description: >- + List of all roles in the environment with their metadata and optionally + their permissions. + type: array + items: + type: object + $ref: ./v1rolesRole.yaml + examples: + - - display_name: Administrator + id: role_1234abcd5678efgh + name: admin + - display_name: Viewer + id: role_9876zyxw5432vuts + name: viewer diff --git a/openapi/components/schemas/rolesPermission.yaml b/openapi/components/schemas/rolesPermission.yaml new file mode 100644 index 000000000..8775a6d8a --- /dev/null +++ b/openapi/components/schemas/rolesPermission.yaml @@ -0,0 +1,20 @@ +type: object +title: Permission Entity +properties: + create_time: + type: string + format: date-time + description: + type: string + id: + type: string + is_scalekit_permission: + description: Indicates whether this permission is predefined by Scalekit + type: boolean + examples: + - true + name: + type: string + update_time: + type: string + format: date-time diff --git a/openapi/components/schemas/rolesPermissionType.yaml b/openapi/components/schemas/rolesPermissionType.yaml new file mode 100644 index 000000000..e8bee763a --- /dev/null +++ b/openapi/components/schemas/rolesPermissionType.yaml @@ -0,0 +1,4 @@ +type: string +enum: + - SCALEKIT + - ENVIRONMENT diff --git a/openapi/components/schemas/rolesRolePermission.yaml b/openapi/components/schemas/rolesRolePermission.yaml new file mode 100644 index 000000000..3c058b6a9 --- /dev/null +++ b/openapi/components/schemas/rolesRolePermission.yaml @@ -0,0 +1,20 @@ +type: object +title: RolePermissions represents a permission with role source information +properties: + create_time: + type: string + format: date-time + description: + type: string + id: + type: string + name: + type: string + role_name: + description: Name of the role from which this permission was sourced + type: string + examples: + - admin_role + update_time: + type: string + format: date-time diff --git a/openapi/components/schemas/rolesUpdateDefaultOrganizationRolesResponse.yaml b/openapi/components/schemas/rolesUpdateDefaultOrganizationRolesResponse.yaml new file mode 100644 index 000000000..2793fcff5 --- /dev/null +++ b/openapi/components/schemas/rolesUpdateDefaultOrganizationRolesResponse.yaml @@ -0,0 +1,10 @@ +type: object +properties: + default_member: + description: Updated default member role + $ref: ./v1rolesRole.yaml + examples: + - description: Role for regular members + display_name: Member Role + id: role_0987654321 + name: member diff --git a/openapi/components/schemas/rolesUpdateDefaultRole.yaml b/openapi/components/schemas/rolesUpdateDefaultRole.yaml new file mode 100644 index 000000000..5110612d2 --- /dev/null +++ b/openapi/components/schemas/rolesUpdateDefaultRole.yaml @@ -0,0 +1,9 @@ +type: object +properties: + id: + type: string + name: + description: Unique name of the role + type: string + examples: + - creator diff --git a/openapi/components/schemas/rolesUpdateDefaultRolesRequest.yaml b/openapi/components/schemas/rolesUpdateDefaultRolesRequest.yaml new file mode 100644 index 000000000..c45658514 --- /dev/null +++ b/openapi/components/schemas/rolesUpdateDefaultRolesRequest.yaml @@ -0,0 +1,34 @@ +type: object +properties: + default_creator: + description: Default creator role (deprecated - use default_creator_role field instead) + $ref: ./rolesUpdateDefaultRole.yaml + examples: + - description: Role for creating resources + display_name: Creator Role + id: role_1234567890 + name: creator + default_creator_role: + description: >- + Name of the role to set as the default creator role. This role will be + automatically assigned to users who create new resources in the + environment. Must be a valid role name that exists in the environment. + type: string + examples: + - creator + default_member: + description: Default member role (deprecated - use default_member_role field instead) + $ref: ./rolesUpdateDefaultRole.yaml + examples: + - description: Role for regular members + display_name: Member Role + id: role_0987654321 + name: member + default_member_role: + description: >- + Name of the role to set as the default member role. This role will be + automatically assigned to new users when they join the environment. Must + be a valid role name that exists in the environment. + type: string + examples: + - member diff --git a/openapi/components/schemas/rolesUpdateDefaultRolesResponse.yaml b/openapi/components/schemas/rolesUpdateDefaultRolesResponse.yaml new file mode 100644 index 000000000..02bfb2ccb --- /dev/null +++ b/openapi/components/schemas/rolesUpdateDefaultRolesResponse.yaml @@ -0,0 +1,22 @@ +type: object +properties: + default_creator: + description: >- + The role that is now set as the default creator role for the environment. + Contains complete role information including permissions and metadata. + $ref: ./v1rolesRole.yaml + examples: + - description: Role for creating resources + display_name: Creator Role + id: role_1234567890 + name: creator + default_member: + description: >- + The role that is now set as the default member role for the environment. + Contains complete role information including permissions and metadata. + $ref: ./v1rolesRole.yaml + examples: + - description: Role for regular members + display_name: Member Role + id: role_0987654321 + name: member diff --git a/openapi/components/schemas/rolesUpdateOrganizationRoleResponse.yaml b/openapi/components/schemas/rolesUpdateOrganizationRoleResponse.yaml new file mode 100644 index 000000000..5f89b49de --- /dev/null +++ b/openapi/components/schemas/rolesUpdateOrganizationRoleResponse.yaml @@ -0,0 +1,4 @@ +type: object +properties: + role: + $ref: ./v1rolesRole.yaml diff --git a/openapi/components/schemas/rolesUpdatePermissionResponse.yaml b/openapi/components/schemas/rolesUpdatePermissionResponse.yaml new file mode 100644 index 000000000..bf007adee --- /dev/null +++ b/openapi/components/schemas/rolesUpdatePermissionResponse.yaml @@ -0,0 +1,4 @@ +type: object +properties: + permission: + $ref: ./rolesPermission.yaml diff --git a/openapi/components/schemas/rolesUpdateRoleResponse.yaml b/openapi/components/schemas/rolesUpdateRoleResponse.yaml new file mode 100644 index 000000000..efe00858f --- /dev/null +++ b/openapi/components/schemas/rolesUpdateRoleResponse.yaml @@ -0,0 +1,10 @@ +type: object +properties: + role: + description: The updated role object with all current configuration details. + $ref: ./v1rolesRole.yaml + examples: + - description: Can edit and approve content + display_name: Senior Editor + id: role_1234abcd5678efgh + name: content_editor diff --git a/openapi/components/schemas/sessionsAuthenticatedClients.yaml b/openapi/components/schemas/sessionsAuthenticatedClients.yaml new file mode 100644 index 000000000..fb043198e --- /dev/null +++ b/openapi/components/schemas/sessionsAuthenticatedClients.yaml @@ -0,0 +1,17 @@ +description: >- + AuthenticatedClients represents an authenticated client in a session along + with its organization context. +type: object +properties: + client_id: + description: Unique identifier of the authenticated client application. + type: string + examples: + - skc_1234567890 + organization_id: + description: >- + Active or last active Organization ID associated with the authenticated + client. + type: string + examples: + - org_1234567890 diff --git a/openapi/components/schemas/sessionsDeviceDetails.yaml b/openapi/components/schemas/sessionsDeviceDetails.yaml new file mode 100644 index 000000000..9df5835cd --- /dev/null +++ b/openapi/components/schemas/sessionsDeviceDetails.yaml @@ -0,0 +1,63 @@ +type: object +properties: + browser: + description: >- + Browser name and family extracted from the user agent. Examples: Chrome, + Safari, Firefox, Edge, Mobile Safari. + type: string + examples: + - Chrome + browser_version: + description: >- + Version of the browser application. Represents the specific release + version of the browser being used. + type: string + examples: + - 120.0.0.0 + device_type: + description: >- + Categorized device type classification. Possible values: 'desktop' + (traditional computers), 'mobile' (smartphones and small tablets), + 'tablet' (large tablets), 'other'. Useful for displaying session + information by device category. + type: string + examples: + - desktop + ip: + description: >- + IP address of the device that initiated the session. This is the + public-facing IP address used to connect to the application. Useful for + security audits and geographic distribution analysis. + type: string + examples: + - 192.0.2.1 + location: + description: >- + Geographic location information derived from IP address geolocation. + Includes country, region, city, and coordinates. Note: Based on IP + location data and may not represent the user's exact physical location. + $ref: ./v1sessionsLocation.yaml + os: + description: >- + Operating system name extracted from the user agent and device headers. + Examples: macOS, Windows, Linux, iOS, Android. + type: string + examples: + - macOS + os_version: + description: >- + Version of the operating system. Represents the specific OS release the + device is running. + type: string + examples: + - '14.2' + user_agent: + description: >- + Complete HTTP User-Agent header string from the client request. Contains + browser type, version, and operating system information. Used for detailed + device fingerprinting and user agent analysis. + type: string + examples: + - >- + Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 + (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 diff --git a/openapi/components/schemas/sessionsRevokeAllUserSessionsResponse.yaml b/openapi/components/schemas/sessionsRevokeAllUserSessionsResponse.yaml new file mode 100644 index 000000000..4a1818f07 --- /dev/null +++ b/openapi/components/schemas/sessionsRevokeAllUserSessionsResponse.yaml @@ -0,0 +1,18 @@ +type: object +properties: + revoked_sessions: + description: >- + List of all sessions that were revoked, including detailed information for + each revoked session with IDs, timestamps, and device details. + type: array + items: + type: object + $ref: ./sessionsRevokedSessionDetails.yaml + total_revoked: + description: >- + Total count of active sessions that were revoked. Useful for confirmation + and audit logging. + type: integer + format: int64 + examples: + - 5 diff --git a/openapi/components/schemas/sessionsRevokeSessionResponse.yaml b/openapi/components/schemas/sessionsRevokeSessionResponse.yaml new file mode 100644 index 000000000..616d64a01 --- /dev/null +++ b/openapi/components/schemas/sessionsRevokeSessionResponse.yaml @@ -0,0 +1,7 @@ +type: object +properties: + revoked_session: + description: >- + Details of the revoked session including session ID, user ID, creation and + revocation timestamps, and final device information. + $ref: ./sessionsRevokedSessionDetails.yaml diff --git a/openapi/components/schemas/sessionsRevokedSessionDetails.yaml b/openapi/components/schemas/sessionsRevokedSessionDetails.yaml new file mode 100644 index 000000000..877bd322f --- /dev/null +++ b/openapi/components/schemas/sessionsRevokedSessionDetails.yaml @@ -0,0 +1,77 @@ +type: object +properties: + absolute_expires_at: + description: >- + The absolute expiration timestamp that was configured for this session + before revocation. Represents the hard deadline regardless of activity. + type: string + format: date-time + examples: + - '2025-01-22T10:30:00Z' + created_at: + description: >- + Timestamp indicating when the session was originally created before + revocation. + type: string + format: date-time + examples: + - '2025-01-15T10:30:00Z' + expired_at: + description: >- + Timestamp when the session was actually terminated. Set to the revocation + time when the session is revoked. + type: string + format: date-time + examples: + - '2025-01-15T12:00:00Z' + idle_expires_at: + description: >- + The idle expiration timestamp that was configured for this session before + revocation. Represents when the session would have expired due to + inactivity. + type: string + format: date-time + examples: + - '2025-01-15T11:30:00Z' + last_active_at: + description: >- + Timestamp of the last recorded user activity in this session before + revocation. Helps identify inactive sessions that were revoked. + type: string + format: date-time + examples: + - '2025-01-15T10:55:30Z' + logout_at: + description: >- + Timestamp when the user explicitly logged out (if applicable). Null if the + session was revoked without prior logout. + type: string + format: date-time + examples: + - '2025-01-15T14:00:00Z' + session_id: + description: >- + Unique identifier for the revoked session. System-generated read-only + field. + type: string + examples: + - ses_1234567890123456 + status: + description: >- + Status of the session after revocation. Always 'revoked' since only active + sessions can be revoked. Sessions that were already expired or logged out + are not included in the revocation response. + type: string + examples: + - revoked + updated_at: + description: Timestamp indicating when the session was last modified before revocation. + type: string + format: date-time + examples: + - '2025-01-15T10:45:00Z' + user_id: + description: Unique identifier for the user who owned this session. + type: string + examples: + - usr_1234567890123456 diff --git a/openapi/components/schemas/sessionsSessionDetails.yaml b/openapi/components/schemas/sessionsSessionDetails.yaml new file mode 100644 index 000000000..5521545f5 --- /dev/null +++ b/openapi/components/schemas/sessionsSessionDetails.yaml @@ -0,0 +1,122 @@ +type: object +properties: + absolute_expires_at: + description: >- + Hard expiration timestamp for the session regardless of user activity. The + session will be forcibly terminated at this time. This represents the + maximum session lifetime from creation. + type: string + format: date-time + examples: + - '2025-01-22T10:30:00Z' + authenticated_clients: + description: >- + Details of the authenticated clients for this session: client ID and + organization context. + type: array + items: + type: object + $ref: ./sessionsAuthenticatedClients.yaml + authenticated_organizations: + description: >- + List of organization IDs that have been authenticated for this user within + the current session. Contains all organizations where the user has + successfully completed SSO or authentication. + type: array + items: + type: string + examples: + - - org_123 + - org_456 + created_at: + description: >- + Timestamp indicating when the session was created. This is set once at + session creation and remains constant throughout the session lifetime. + type: string + format: date-time + examples: + - '2025-01-15T10:30:00Z' + device: + description: >- + Complete device metadata associated with this session including browser, + operating system, device type, and geographic location based on IP + address. + $ref: ./sessionsDeviceDetails.yaml + expired_at: + description: >- + Timestamp when the session was terminated. Null if the session is still + active. Set when the session expires due to reaching idle_expires_at or + absolute_expires_at timeout, or when administratively revoked. Not set for + user-initiated logout (see logout_at instead). + type: string + format: date-time + examples: + - '2025-01-15T12:00:00Z' + idle_expires_at: + description: >- + Projected expiration timestamp if the session remains idle without user + activity. This timestamp is recalculated with each user activity. Session + will be automatically terminated at this time if no activity occurs. + type: string + format: date-time + examples: + - '2025-01-15T11:30:00Z' + last_active_at: + description: >- + Timestamp of the most recent user activity detected in this session. + Updated on each API request or user interaction. Used to determine if a + session has exceeded the idle timeout threshold. + type: string + format: date-time + examples: + - '2025-01-15T10:55:30Z' + logout_at: + description: >- + Timestamp when the user explicitly logged out from the session. Null if + the user has not logged out. When set, indicates the session ended due to + explicit user logout rather than timeout. + type: string + format: date-time + examples: + - '2025-01-15T14:00:00Z' + organization_id: + description: >- + Organization ID for the user's most recently active organization within + this session. This represents the primary organization context for the + current session. + type: string + examples: + - org_1234567890123456 + session_id: + description: >- + Unique identifier for the session. System-generated read-only field used + to reference this session. + type: string + examples: + - ses_1234567890123456 + status: + description: >- + Current operational status of the session. Possible values: 'active' + (session is valid and requests are allowed), 'expired' (session terminated + due to idle or absolute timeout), 'revoked' (session was administratively + revoked), 'logout' (user explicitly logged out). Use this to determine if + the session can be used for new requests. + type: string + examples: + - active + updated_at: + description: >- + Timestamp indicating when the session was last updated. Updated whenever + session state changes such as organization context changes or metadata + updates. + type: string + format: date-time + examples: + - '2025-01-15T10:45:00Z' + user_id: + description: >- + Unique identifier for the user who owns and is authenticated within this + session. + type: string + examples: + - usr_1234567890123456 diff --git a/openapi/components/schemas/sessionsUserSessionDetails.yaml b/openapi/components/schemas/sessionsUserSessionDetails.yaml new file mode 100644 index 000000000..f56fc8fcc --- /dev/null +++ b/openapi/components/schemas/sessionsUserSessionDetails.yaml @@ -0,0 +1,33 @@ +type: object +properties: + next_page_token: + description: >- + Pagination token for retrieving the next page of results. Empty string if + there are no more pages (you have reached the final page of results). + type: string + examples: + - eyJwYWdlIjogMiwgImxhc3RfaWQiOiAic2VzXzEyMzQ1In0= + prev_page_token: + description: >- + Pagination token for retrieving the previous page of results. Empty string + for the first page. Use this to navigate backward through result pages. + type: string + examples: + - eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInNlc183OTAxIn0= + sessions: + description: >- + Array of session objects for the requested user. May contain fewer entries + than the requested page_size when reaching the final page of results. + type: array + items: + type: object + $ref: ./sessionsSessionDetails.yaml + total_size: + description: >- + Total number of sessions matching the applied filter criteria, regardless + of pagination. This represents the complete result set size before + pagination is applied. + type: integer + format: int64 + examples: + - 42 diff --git a/openapi/components/schemas/sessionsUserSessionFilter.yaml b/openapi/components/schemas/sessionsUserSessionFilter.yaml new file mode 100644 index 000000000..ffe6def48 --- /dev/null +++ b/openapi/components/schemas/sessionsUserSessionFilter.yaml @@ -0,0 +1,31 @@ +type: object +properties: + end_time: + description: >- + Filter to include only sessions created on or before this timestamp. + Optional. Uses RFC 3339 format. Must be after start_time if both are + specified. + type: string + format: date-time + examples: + - '2025-12-31T23:59:59Z' + start_time: + description: >- + Filter to include only sessions created on or after this timestamp. + Optional. Uses RFC 3339 format. Useful for querying sessions within a + specific time window. + type: string + format: date-time + examples: + - '2025-01-01T00:00:00Z' + status: + description: >- + Filter sessions by one or more status values. Possible values: 'active', + 'expired', 'revoked', 'logout'. Leave empty to include all statuses. + Multiple values use OR logic (e.g., status=['active', 'expired'] returns + sessions that are either active OR expired). + type: array + items: + type: string + examples: + - - active diff --git a/openapi/components/schemas/toolsExecuteToolRequest.yaml b/openapi/components/schemas/toolsExecuteToolRequest.yaml new file mode 100644 index 000000000..e16fee58f --- /dev/null +++ b/openapi/components/schemas/toolsExecuteToolRequest.yaml @@ -0,0 +1,64 @@ +type: object +properties: + agent_run_id: + description: >- + Optional. Customer-supplied identifier grouping multiple tool calls into a + single agent run. Useful for correlating logs across an agentic workflow. + type: string + examples: + - run_abc123 + connected_account_id: + description: >- + Optional. The unique ID of the connected account. Use this to directly + identify the connected account instead of using identifier + connector + combination. + type: string + examples: + - ca_123 + connector: + description: >- + Optional. The name of the connector/provider (e.g., 'Google Workspace', + 'Slack', 'Notion'). Alphanumeric characters, spaces, hyphens, underscores, + and colons are allowed. Use this in combination with identifier to + identify the connected account. + type: string + examples: + - Google Workspace + identifier: + description: >- + Optional. The unique identifier for the connected account within the + third-party service (e.g., email address, user ID, workspace identifier). + Use this in combination with connector to identify the connected account. + type: string + examples: + - user@example.com + organization_id: + description: >- + Optional. The organization ID to scope the connected account lookup. Use + this to narrow down the search when the same identifier exists across + multiple organizations. + type: string + examples: + - org_123 + params: + description: >- + JSON object containing the parameters required for tool execution. The + structure depends on the specific tool being executed. + type: object + examples: + - body: Hello World + subject: Hello + to: user@example.com + tool_name: + description: Name of the tool to execute + type: string + examples: + - send_email + user_id: + description: >- + Optional. The user ID to scope the connected account lookup. Use this to + narrow down the search when the same identifier exists across multiple + users. + type: string + examples: + - user_123 diff --git a/openapi/components/schemas/toolsExecuteToolResponse.yaml b/openapi/components/schemas/toolsExecuteToolResponse.yaml new file mode 100644 index 000000000..965cd87f1 --- /dev/null +++ b/openapi/components/schemas/toolsExecuteToolResponse.yaml @@ -0,0 +1,14 @@ +type: object +properties: + data: + description: Free-flowing JSON parameters for the tool execution + type: object + examples: + - body: Hello World + subject: Hello + to: user@example.com + execution_id: + description: Unique identifier for the tool execution + type: string + examples: + - '123456789' diff --git a/openapi/components/schemas/usersCreateMembershipResponse.yaml b/openapi/components/schemas/usersCreateMembershipResponse.yaml new file mode 100644 index 000000000..5a4b62aad --- /dev/null +++ b/openapi/components/schemas/usersCreateMembershipResponse.yaml @@ -0,0 +1,4 @@ +type: object +properties: + user: + $ref: ./usersUser.yaml diff --git a/openapi/components/schemas/usersCreateUser.yaml b/openapi/components/schemas/usersCreateUser.yaml new file mode 100644 index 000000000..708f7a91c --- /dev/null +++ b/openapi/components/schemas/usersCreateUser.yaml @@ -0,0 +1,36 @@ +type: object +properties: + email: + description: >- + Primary email address for the user. Must be unique across the environment + and valid per RFC 5322. + type: string + examples: + - user@example.com + external_id: + description: >- + Your application's unique identifier for this organization, used to link + Scalekit with your system. + type: string + examples: + - ext_12345a67b89c + membership: + description: >- + List of organization memberships. Automatically populated based on group + assignments. + $ref: ./v1usersCreateMembership.yaml + metadata: + description: >- + Custom key-value pairs for storing additional user context. Keys (3-25 + chars), values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - department: engineering + location: nyc-office + user_profile: + description: >- + User's personal information including name, address, and other profile + attributes. + $ref: ./usersCreateUserProfile.yaml diff --git a/openapi/components/schemas/usersCreateUserAndMembershipResponse.yaml b/openapi/components/schemas/usersCreateUserAndMembershipResponse.yaml new file mode 100644 index 000000000..5a4b62aad --- /dev/null +++ b/openapi/components/schemas/usersCreateUserAndMembershipResponse.yaml @@ -0,0 +1,4 @@ +type: object +properties: + user: + $ref: ./usersUser.yaml diff --git a/openapi/components/schemas/usersCreateUserProfile.yaml b/openapi/components/schemas/usersCreateUserProfile.yaml new file mode 100644 index 000000000..7678afe60 --- /dev/null +++ b/openapi/components/schemas/usersCreateUserProfile.yaml @@ -0,0 +1,76 @@ +type: object +properties: + custom_attributes: + description: >- + Custom attributes for extended user profile data. Keys (3-25 chars), + values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - department: engineering + security_clearance: level2 + family_name: + description: User's family name. Maximum 255 characters. + type: string + examples: + - Doe + gender: + description: User's gender identity. + type: string + examples: + - male + given_name: + description: User's given name. Maximum 255 characters. + type: string + examples: + - John + groups: + description: >- + List of group names the user belongs to. Each group name must be 1-250 + characters + type: array + items: + type: string + examples: + - - engineering + - managers + locale: + description: >- + User's localization preference in BCP-47 format. Defaults to organization + settings. + type: string + examples: + - en-US + metadata: + description: >- + System-managed key-value pairs for internal tracking. Keys (3-25 chars), + values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - account_status: active + signup_source: mobile_app + name: + description: Full name in display format. Typically combines first_name and last_name. + type: string + examples: + - John Michael Doe + phone_number: + description: >- + Phone number in E.164 international format. Required for SMS-based + authentication. + type: string + examples: + - '+14155552671' + picture: + description: URL to the user's profile picture or avatar. + type: string + examples: + - https://example.com/avatar.jpg + preferred_username: + description: User's preferred username for display purposes. + type: string + examples: + - John Michael Doe diff --git a/openapi/components/schemas/usersGetUserResponse.yaml b/openapi/components/schemas/usersGetUserResponse.yaml new file mode 100644 index 000000000..5a4b62aad --- /dev/null +++ b/openapi/components/schemas/usersGetUserResponse.yaml @@ -0,0 +1,4 @@ +type: object +properties: + user: + $ref: ./usersUser.yaml diff --git a/openapi/components/schemas/usersInvite.yaml b/openapi/components/schemas/usersInvite.yaml new file mode 100644 index 000000000..d07754b42 --- /dev/null +++ b/openapi/components/schemas/usersInvite.yaml @@ -0,0 +1,48 @@ +type: object +properties: + created_at: + description: Timestamp when the invite was originally created. + type: string + format: date-time + examples: + - '2025-07-10T08:00:00Z' + expires_at: + description: The time at which the invite expires. + type: string + format: date-time + examples: + - '2025-12-31T23:59:59Z' + inviter_email: + description: Identifier of the user or system that initiated the invite. + type: string + examples: + - admin@example.com + organization_id: + description: The organization to which the invite belongs. + type: string + examples: + - org_987654321 + resent_at: + description: Timestamp when the invite was last resent, if applicable. + type: string + format: date-time + examples: + - '2025-07-15T09:30:00Z' + resent_count: + description: Number of times the invite has been resent. + type: integer + format: int32 + examples: + - 2 + status: + description: Current status of the invite (e.g., pending, accepted, expired, revoked). + type: string + examples: + - pending_invite + user_id: + description: >- + User ID to whom the invite is sent. May be empty if the user has not + signed up yet. + type: string + examples: + - usr_123456 diff --git a/openapi/components/schemas/usersListOrganizationUsersResponse.yaml b/openapi/components/schemas/usersListOrganizationUsersResponse.yaml new file mode 100644 index 000000000..622c7ab24 --- /dev/null +++ b/openapi/components/schemas/usersListOrganizationUsersResponse.yaml @@ -0,0 +1,32 @@ +type: object +properties: + next_page_token: + description: >- + Opaque token for retrieving the next page of results. Empty if there are + no more pages. + type: string + examples: + - eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0= + prev_page_token: + description: >- + Opaque token for retrieving the previous page of results. Empty for the + first page. + type: string + examples: + - eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9 + total_size: + description: >- + Total number of users matching the request criteria, regardless of + pagination. + type: integer + format: int64 + examples: + - 1042 + users: + description: >- + List of user objects for the current page. May contain fewer entries than + requested page_size. + type: array + items: + type: object + $ref: ./usersUser.yaml diff --git a/openapi/components/schemas/usersListUserPermissionsResponse.yaml b/openapi/components/schemas/usersListUserPermissionsResponse.yaml new file mode 100644 index 000000000..53c967305 --- /dev/null +++ b/openapi/components/schemas/usersListUserPermissionsResponse.yaml @@ -0,0 +1,8 @@ +type: object +properties: + permissions: + description: List of permissions the user has access to + type: array + items: + type: object + $ref: ./usersPermission.yaml diff --git a/openapi/components/schemas/usersListUserRolesResponse.yaml b/openapi/components/schemas/usersListUserRolesResponse.yaml new file mode 100644 index 000000000..3773814b8 --- /dev/null +++ b/openapi/components/schemas/usersListUserRolesResponse.yaml @@ -0,0 +1,8 @@ +type: object +properties: + roles: + description: List of roles assigned to the user + type: array + items: + type: object + $ref: ./commonsRole.yaml diff --git a/openapi/components/schemas/usersListUsersResponse.yaml b/openapi/components/schemas/usersListUsersResponse.yaml new file mode 100644 index 000000000..e20573b7a --- /dev/null +++ b/openapi/components/schemas/usersListUsersResponse.yaml @@ -0,0 +1,30 @@ +type: object +properties: + next_page_token: + description: >- + Token for retrieving the next page of results. Empty if there are no more + pages. + type: string + examples: + - eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0= + prev_page_token: + description: >- + Token for retrieving the previous page of results. Empty if this is the + first page. + type: string + examples: + - eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9 + total_size: + description: >- + Total number of users matching the request criteria, regardless of + pagination. + type: integer + format: int64 + examples: + - 1042 + users: + description: List of users. + type: array + items: + type: object + $ref: ./usersUser.yaml diff --git a/openapi/components/schemas/usersPermission.yaml b/openapi/components/schemas/usersPermission.yaml new file mode 100644 index 000000000..aeb0f039c --- /dev/null +++ b/openapi/components/schemas/usersPermission.yaml @@ -0,0 +1,18 @@ +type: object +properties: + description: + description: Description of what the permission allows + type: string + examples: + - Allows creating new user accounts + id: + description: Unique identifier for the permission + type: string + readOnly: true + examples: + - perm_1234abcd5678efgh + name: + description: Unique name identifier for the permission + type: string + examples: + - users:create diff --git a/openapi/components/schemas/usersResendInviteResponse.yaml b/openapi/components/schemas/usersResendInviteResponse.yaml new file mode 100644 index 000000000..bcf0c3796 --- /dev/null +++ b/openapi/components/schemas/usersResendInviteResponse.yaml @@ -0,0 +1,13 @@ +type: object +properties: + invite: + description: >- + Updated invitation object containing the resent invitation details, + including new expiration time and incremented resend counter. + $ref: ./usersInvite.yaml + examples: + - expires_at: '2025-12-31T23:59:59Z' + organization_id: org_123 + resent_count: 2 + status: pending_invite + user_id: usr_456 diff --git a/openapi/components/schemas/usersSearchOrganizationUsersResponse.yaml b/openapi/components/schemas/usersSearchOrganizationUsersResponse.yaml new file mode 100644 index 000000000..afea25037 --- /dev/null +++ b/openapi/components/schemas/usersSearchOrganizationUsersResponse.yaml @@ -0,0 +1,30 @@ +type: object +properties: + next_page_token: + description: >- + Token for retrieving the next page of results. Empty if there are no more + pages. + type: string + examples: + - eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0= + prev_page_token: + description: >- + Token for retrieving the previous page of results. Empty if this is the + first page. + type: string + examples: + - eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9 + total_size: + description: >- + Total number of users matching the request criteria, regardless of + pagination. + type: integer + format: int64 + examples: + - 1042 + users: + description: List of matching users. + type: array + items: + type: object + $ref: ./usersUser.yaml diff --git a/openapi/components/schemas/usersSearchUsersResponse.yaml b/openapi/components/schemas/usersSearchUsersResponse.yaml new file mode 100644 index 000000000..afea25037 --- /dev/null +++ b/openapi/components/schemas/usersSearchUsersResponse.yaml @@ -0,0 +1,30 @@ +type: object +properties: + next_page_token: + description: >- + Token for retrieving the next page of results. Empty if there are no more + pages. + type: string + examples: + - eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0= + prev_page_token: + description: >- + Token for retrieving the previous page of results. Empty if this is the + first page. + type: string + examples: + - eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9 + total_size: + description: >- + Total number of users matching the request criteria, regardless of + pagination. + type: integer + format: int64 + examples: + - 1042 + users: + description: List of matching users. + type: array + items: + type: object + $ref: ./usersUser.yaml diff --git a/openapi/components/schemas/usersUpdateMembershipResponse.yaml b/openapi/components/schemas/usersUpdateMembershipResponse.yaml new file mode 100644 index 000000000..5a4b62aad --- /dev/null +++ b/openapi/components/schemas/usersUpdateMembershipResponse.yaml @@ -0,0 +1,4 @@ +type: object +properties: + user: + $ref: ./usersUser.yaml diff --git a/openapi/components/schemas/usersUpdateUserProfile.yaml b/openapi/components/schemas/usersUpdateUserProfile.yaml new file mode 100644 index 000000000..cec063010 --- /dev/null +++ b/openapi/components/schemas/usersUpdateUserProfile.yaml @@ -0,0 +1,138 @@ +type: object +properties: + custom_attributes: + description: >- + Updates custom attributes for extended user profile data and + application-specific information. Use this field to store + business-specific user data like department, job title, security + clearances, project assignments, or any other organizational attributes + your application requires. Unlike system metadata, these attributes are + typically managed by administrators or applications and are visible to end + users. Keys must be 3-25 characters, values must be 1-256 characters, with + a maximum of 20 key-value pairs. + type: object + additionalProperties: + type: string + examples: + - department: engineering + security_clearance: level2 + family_name: + description: >- + Updates the user's family name (last name or surname). Use this field to + modify how the user's last name appears throughout the system. Maximum 255 + characters allowed. + type: string + examples: + - Doe + first_name: + description: >- + [DEPRECATED] Use given_name instead. User's given name. Maximum 200 + characters. + type: string + examples: + - John + gender: + description: >- + Updates the user's gender identity information. Use this field to store + the user's gender identity for personalization, compliance, or reporting + purposes. This field supports any string value to accommodate diverse + gender identities and should be handled with appropriate privacy + considerations according to your organization's policies. + type: string + examples: + - male + given_name: + description: >- + Updates the user's given name (first name). Use this field to modify how + the user's first name appears in the system and user interfaces. Maximum + 255 characters allowed. + type: string + examples: + - John + groups: + description: >- + Updates the list of group names the user belongs to within the + organization. Use this field to manage the user's group memberships for + role-based access control, team assignments, or organizational structure. + Groups are typically used for permission management and collaborative + access. Each group name must be unique within the list, 1-250 characters + long, with a maximum of 50 groups per user. + type: array + items: + type: string + examples: + - - engineering + - managers + last_name: + description: >- + [DEPRECATED] Use family_name instead. User's family name. Maximum 200 + characters. + type: string + examples: + - Doe + locale: + description: >- + Updates the user's preferred language and region settings using BCP-47 + format codes. Use this field to customize the user's experience with + localized content, date formats, number formatting, and UI language. When + not specified, the user inherits the organization's default locale + settings. Common values include `en-US`, `en-GB`, `fr-FR`, `de-DE`, and + `es-ES`. + type: string + examples: + - en-US + metadata: + description: >- + Updates system-managed key-value pairs for internal tracking and + operational data. Use this field to store system-generated metadata like + account status, signup source, last activity tracking, or + integration-specific identifiers. These fields are typically managed by + automated processes rather than direct user input. Keys must be 3-25 + characters, values must be 1-256 characters, with a maximum of 20 + key-value pairs. + type: object + additionalProperties: + type: string + examples: + - account_status: active + signup_source: mobile_app + name: + description: >- + Updates the user's complete display name. Use this field when you want to + set the full name as a single string rather than using separate given and + family names. This name appears in user interfaces, reports, and anywhere + a formatted display name is needed. + type: string + examples: + - John Doe + phone_number: + description: >- + Updates the user's phone number in E.164 international format. Use this + field to enable SMS-based authentication methods, two-factor + authentication, or phone-based account recovery. The phone number must + include the country code and be formatted according to E.164 standards + (e.g., `+1` for US numbers). This field is required when enabling SMS + authentication features. + type: string + examples: + - '+14155552671' + picture: + description: >- + Updates the URL to the user's profile picture or avatar image. Use this + field to set or change the user's profile photo that appears in user + interfaces, directory listings, and collaborative features. The URL should + point to a publicly accessible image file. Supported formats typically + include JPEG, PNG, and GIF. Maximum URL length is 2048 characters. + type: string + examples: + - https://example.com/avatar.jpg + preferred_username: + description: >- + Updates the user's preferred username for display and identification + purposes. Use this field to set a custom username that the user prefers to + be known by, which may differ from their email or formal name. This + username appears in user interfaces, mentions, and informal + communications. Maximum 512 characters allowed. + type: string + examples: + - John Michael Doe diff --git a/openapi/components/schemas/usersUpdateUserResponse.yaml b/openapi/components/schemas/usersUpdateUserResponse.yaml new file mode 100644 index 000000000..5a4b62aad --- /dev/null +++ b/openapi/components/schemas/usersUpdateUserResponse.yaml @@ -0,0 +1,4 @@ +type: object +properties: + user: + $ref: ./usersUser.yaml diff --git a/openapi/components/schemas/usersUser.yaml b/openapi/components/schemas/usersUser.yaml new file mode 100644 index 000000000..96d7dd7bd --- /dev/null +++ b/openapi/components/schemas/usersUser.yaml @@ -0,0 +1,65 @@ +type: object +properties: + create_time: + description: >- + Timestamp when the user account was initially created. Automatically set + by the server. + type: string + format: date-time + readOnly: true + email: + description: >- + Primary email address for the user. Must be unique across the environment + and valid per RFC 5322. + type: string + examples: + - user@example.com + external_id: + description: >- + Your application's unique identifier for this organization, used to link + Scalekit with your system. + type: string + examples: + - ext_12345a67b89c + id: + description: Unique system-generated identifier for the user. Immutable once created. + type: string + examples: + - usr_1234abcd5678efgh + last_login_time: + description: >- + Timestamp of the user's most recent successful authentication. Updated + automatically. + type: string + format: date-time + readOnly: true + memberships: + description: >- + List of organization memberships. Automatically populated based on group + assignments. + type: array + items: + type: object + $ref: ./commonsOrganizationMembership.yaml + metadata: + description: >- + Custom key-value pairs for storing additional user context. Keys (3-25 + chars), values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - department: engineering + location: nyc-office + update_time: + description: >- + Timestamp of the last modification to the user account. Automatically + updated by the server. + type: string + format: date-time + readOnly: true + user_profile: + description: >- + User's personal information including name, address, and other profile + attributes. + $ref: ./commonsUserProfile.yaml diff --git a/openapi/components/schemas/v1connected_accountsCreateConnectedAccount.yaml b/openapi/components/schemas/v1connected_accountsCreateConnectedAccount.yaml new file mode 100644 index 000000000..6c71918a9 --- /dev/null +++ b/openapi/components/schemas/v1connected_accountsCreateConnectedAccount.yaml @@ -0,0 +1,27 @@ +type: object +title: >- + Payload for creating a new connected account - authorization details are + optional +properties: + api_config: + description: >- + Optional JSON configuration for connector-specific API settings such as + rate limits, custom API endpoints, timeouts, or feature flags. + type: object + examples: + - base_url: https://api.custom-domain.com + rate_limit: 1000 + timeout: 30 + authorization_details: + description: >- + Optional authentication credentials for the connected account. Include + OAuth tokens (access_token, refresh_token, scopes) or static auth details + (API keys, bearer tokens). Can be provided later via update. + $ref: ./connected_accountsAuthorizationDetails.yaml + examples: + - oauth_token: + access_token: ya29.a0... + refresh_token: 1//0g... + scopes: + - email + - profile diff --git a/openapi/components/schemas/v1connected_accountsUpdateConnectedAccount.yaml b/openapi/components/schemas/v1connected_accountsUpdateConnectedAccount.yaml new file mode 100644 index 000000000..a8f33e212 --- /dev/null +++ b/openapi/components/schemas/v1connected_accountsUpdateConnectedAccount.yaml @@ -0,0 +1,25 @@ +type: object +title: Payload for updating an existing connected account - all fields optional +properties: + api_config: + description: >- + Updated JSON configuration for API-specific settings. Merges with existing + configuration - only provided fields are modified. + type: object + examples: + - rate_limit: 2000 + timeout: 60 + authorization_details: + description: >- + Updated authentication credentials. Provide new OAuth tokens (e.g., after + refresh) or updated static auth details. Only included fields will be + modified. + $ref: ./connected_accountsAuthorizationDetails.yaml + examples: + - oauth_token: + access_token: ya29.new_token... + refresh_token: 1//0g... + scopes: + - email + - profile + - calendar diff --git a/openapi/components/schemas/v1domainsCreateDomain.yaml b/openapi/components/schemas/v1domainsCreateDomain.yaml new file mode 100644 index 000000000..e2719d5ab --- /dev/null +++ b/openapi/components/schemas/v1domainsCreateDomain.yaml @@ -0,0 +1,22 @@ +type: object +properties: + domain: + description: >- + The domain name to be configured. Must be a valid business domain you + control. Public and disposable domains (gmail.com, outlook.com, etc.) are + automatically blocked for security. + type: string + examples: + - customerdomain.com + domain_type: + description: > + The domain type. + + - ALLOWED_EMAIL_DOMAIN: trusted domain used to suggest the organization in + the organization switcher during sign-in/sign-up. + + - ORGANIZATION_DOMAIN: SSO discovery domain used to route users to the + correct SSO provider and enforce SSO. + $ref: ./domainsDomainType.yaml + examples: + - ORGANIZATION_DOMAIN diff --git a/openapi/components/schemas/v1organizationsCreateOrganization.yaml b/openapi/components/schemas/v1organizationsCreateOrganization.yaml new file mode 100644 index 000000000..efd079f81 --- /dev/null +++ b/openapi/components/schemas/v1organizationsCreateOrganization.yaml @@ -0,0 +1,41 @@ +type: object +required: + - display_name +properties: + display_name: + description: Name of the organization. Must be between 1 and 200 characters. + type: string + examples: + - Megasoft Inc + external_id: + description: >- + Your application's unique identifier for this organization, used to link + Scalekit with your system. + type: string + examples: + - my_unique_id + logo_url: + description: >- + HTTPS URL of the organization's logo image. Maximum 2048 characters. Must + use the https scheme. + type: string + format: uri + maxLength: 2048 + pattern: ^https:// + examples: + - https://cdn.example.com/acme-logo.png + metadata: + type: object + additionalProperties: + type: string + slug: + description: >- + DNS-safe slug for dynamic redirect URI resolution (e.g. acme for + https://acme.example.com/callback). Lowercase alphanumeric and hyphens, + 1-63 chars, must start and end with alphanumeric, unique per environment. + type: string + maxLength: 63 + minLength: 1 + pattern: ^[a-z0-9]([a-z0-9]|-[a-z0-9])*$ + examples: + - acme diff --git a/openapi/components/schemas/v1organizationsUpdateOrganization.yaml b/openapi/components/schemas/v1organizationsUpdateOrganization.yaml new file mode 100644 index 000000000..038b6fb68 --- /dev/null +++ b/openapi/components/schemas/v1organizationsUpdateOrganization.yaml @@ -0,0 +1,47 @@ +description: For update messages ensure the indexes are same as the base model itself. +type: object +properties: + display_name: + description: >- + Name of the organization to display in the UI. Must be between 1 and 200 + characters + type: string + examples: + - Acme Corporation + external_id: + description: >- + Your application's unique identifier for this organization, used to link + Scalekit with your system + type: string + examples: + - tenant_12345 + logo_url: + description: >- + HTTPS URL of the organization's logo image. Maximum 2048 characters. Must + use the https scheme. + type: string + format: uri + maxLength: 2048 + pattern: ^https:// + examples: + - https://cdn.example.com/acme-logo.png + metadata: + description: >- + Custom key-value pairs to store with the organization. Keys must be 3-25 + characters, values must be 1-256 characters. Maximum 10 pairs allowed. + type: object + additionalProperties: + type: string + examples: + - industry: technology + slug: + description: >- + DNS-safe slug for dynamic redirect URI resolution. Lowercase alphanumeric + and hyphens, 1-63 chars, must start and end with alphanumeric, unique per + environment. + type: string + maxLength: 63 + minLength: 1 + pattern: ^[a-z0-9]([a-z0-9]|-[a-z0-9])*$ + examples: + - acme diff --git a/openapi/components/schemas/v1rolesCreateOrganizationRole.yaml b/openapi/components/schemas/v1rolesCreateOrganizationRole.yaml new file mode 100644 index 000000000..bad350919 --- /dev/null +++ b/openapi/components/schemas/v1rolesCreateOrganizationRole.yaml @@ -0,0 +1,32 @@ +type: object +properties: + description: + description: Description of the organization's role + type: string + examples: + - Organization Viewer Role will be used only for viewing the objects + display_name: + description: Display name of the organization's role + type: string + examples: + - Organization Viewer Role + extends: + description: Base role name for hierarchical roles + type: string + examples: + - admin_role + name: + description: Unique name of the organization's role + type: string + examples: + - org_viewer_role + permissions: + description: >- + List of permission names to assign to this role. Permissions must exist in + the current environment. + type: array + items: + type: string + examples: + - - read:users + - write:documents diff --git a/openapi/components/schemas/v1rolesCreatePermission.yaml b/openapi/components/schemas/v1rolesCreatePermission.yaml new file mode 100644 index 000000000..d530e4945 --- /dev/null +++ b/openapi/components/schemas/v1rolesCreatePermission.yaml @@ -0,0 +1,12 @@ +type: object +properties: + description: + description: Description of the permission + type: string + examples: + - Allows user to read documents from the system + name: + description: Unique name/ID of the permission + type: string + examples: + - read:documents diff --git a/openapi/components/schemas/v1rolesCreateRole.yaml b/openapi/components/schemas/v1rolesCreateRole.yaml new file mode 100644 index 000000000..0f8646e86 --- /dev/null +++ b/openapi/components/schemas/v1rolesCreateRole.yaml @@ -0,0 +1,44 @@ +type: object +properties: + description: + description: >- + Detailed description of the role's purpose, capabilities, and intended use + cases. Maximum 2000 characters. + type: string + examples: + - >- + Can create, edit, and publish content but cannot delete content or + manage user accounts + display_name: + description: >- + Human-readable display name for the role. Used in user interfaces, + reports, and user-facing communications. + type: string + examples: + - Content Editor + extends: + description: >- + Name of the base role that this role extends. Enables hierarchical role + inheritance where this role inherits all permissions from the base role. + type: string + examples: + - viewer + name: + description: >- + Unique name identifier for the role. Must be alphanumeric with + underscores, 1-64 characters. This name is used in API calls and cannot be + changed after creation. + type: string + examples: + - content_editor + permissions: + description: >- + List of permission names to assign to this role. Permissions must exist in + the current environment. Maximum 100 permissions per role. + type: array + items: + type: string + examples: + - - read:content + - write:content + - publish:content diff --git a/openapi/components/schemas/v1rolesRole.yaml b/openapi/components/schemas/v1rolesRole.yaml new file mode 100644 index 000000000..a3e7d14c7 --- /dev/null +++ b/openapi/components/schemas/v1rolesRole.yaml @@ -0,0 +1,74 @@ +type: object +properties: + default_creator: + description: Indicates if this role is the default creator role for new organizations. + type: boolean + examples: + - true + default_member: + description: Indicates if this role is the default member role for new users. + type: boolean + examples: + - true + dependent_roles_count: + description: >- + Number of roles that extend from this role (dependent roles count). + Read-only field. + type: integer + format: int32 + examples: + - 3 + description: + description: >- + Detailed description of the role's purpose and capabilities. Maximum 2000 + characters. + type: string + examples: + - Can create, edit, and publish content but cannot delete or manage users + display_name: + description: >- + Human-readable display name for the role. Used in user interfaces and + reports. + type: string + examples: + - Content Editor + extends: + description: >- + Name of the base role that this role extends. Enables hierarchical role + inheritance. + type: string + examples: + - admin_role + id: + description: Unique system-generated identifier for the role. Immutable once created. + type: string + readOnly: true + examples: + - role_1234abcd5678efgh + is_org_role: + description: Indicates if this role is an organization role. + type: boolean + examples: + - true + name: + description: >- + Unique name identifier for the role. Must be alphanumeric with + underscores, 1-100 characters. + type: string + examples: + - content_editor + permissions: + description: >- + List of permissions with role source information. Only included when + 'include' parameter is specified in the request. + type: array + items: + type: object + $ref: ./rolesRolePermission.yaml + examples: + - - description: Read Content + name: read:content + role_name: admin_role + - description: Write Content + name: write:content + role_name: editor_role diff --git a/openapi/components/schemas/v1rolesUpdateRole.yaml b/openapi/components/schemas/v1rolesUpdateRole.yaml new file mode 100644 index 000000000..f21f9d966 --- /dev/null +++ b/openapi/components/schemas/v1rolesUpdateRole.yaml @@ -0,0 +1,38 @@ +type: object +properties: + description: + description: >- + Detailed description of the role's purpose, capabilities, and intended use + cases. Maximum 2000 characters. + type: string + examples: + - >- + Can create, edit, publish, and approve content. Cannot delete content or + manage user accounts. + display_name: + description: >- + Human-readable display name for the role. Used in user interfaces, + reports, and user-facing communications. + type: string + examples: + - Senior Content Editor + extends: + description: >- + Name of the base role that this role extends. Enables hierarchical role + inheritance where this role inherits all permissions from the base role. + type: string + examples: + - content_editor + permissions: + description: >- + List of permission names to assign to this role. When provided, this + replaces all existing role-permission mappings. Permissions must exist in + the current environment. Maximum 100 permissions per role. + type: array + items: + type: string + examples: + - - read:content + - write:content + - publish:content + - approve:content diff --git a/openapi/components/schemas/v1sessionsLocation.yaml b/openapi/components/schemas/v1sessionsLocation.yaml new file mode 100644 index 000000000..82a17d175 --- /dev/null +++ b/openapi/components/schemas/v1sessionsLocation.yaml @@ -0,0 +1,38 @@ +type: object +properties: + city: + description: >- + City name where the session originated based on IP geolocation. + Approximate location derived from IP address. + type: string + examples: + - San Francisco + latitude: + description: >- + Latitude coordinate of the estimated location. Decimal format (e.g., + '37.7749'). Note: Represents IP geolocation center and may not be precise. + type: string + examples: + - '37.7749' + longitude: + description: >- + Longitude coordinate of the estimated location. Decimal format (e.g., + '-122.4194'). Note: Represents IP geolocation center and may not be + precise. + type: string + examples: + - '-122.4194' + region: + description: >- + Geographic region name derived from IP geolocation. Represents the + country-level location (e.g., 'United States', 'France'). + type: string + examples: + - United States + region_subdivision: + description: >- + Regional subdivision code or name (e.g., state abbreviation for US, + province for Canada). Two-letter ISO format when applicable. + type: string + examples: + - CA diff --git a/openapi/components/schemas/v1usersCreateMembership.yaml b/openapi/components/schemas/v1usersCreateMembership.yaml new file mode 100644 index 000000000..e64b3ba1a --- /dev/null +++ b/openapi/components/schemas/v1usersCreateMembership.yaml @@ -0,0 +1,27 @@ +type: object +properties: + inviter_email: + description: >- + Email address of the user who invited this member. Must be a valid email + address. + type: string + examples: + - john.doe@example.com + metadata: + description: >- + Custom key-value pairs for storing additional user context. Keys (3-25 + chars), values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - department: engineering + location: nyc-office + roles: + description: Role to assign to the user within the organization + type: array + items: + type: object + $ref: ./commonsRole.yaml + examples: + - - name: admin diff --git a/openapi/components/schemas/v1usersUpdateMembership.yaml b/openapi/components/schemas/v1usersUpdateMembership.yaml new file mode 100644 index 000000000..a3858dfc1 --- /dev/null +++ b/openapi/components/schemas/v1usersUpdateMembership.yaml @@ -0,0 +1,20 @@ +type: object +properties: + metadata: + description: >- + Custom key-value pairs for storing additional user context. Keys (3-25 + chars), values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - department: engineering + location: nyc-office + roles: + description: Role to assign to the user within the organization + type: array + items: + type: object + $ref: ./commonsRole.yaml + examples: + - - name: admin diff --git a/openapi/components/schemas/v1usersUpdateUser.yaml b/openapi/components/schemas/v1usersUpdateUser.yaml new file mode 100644 index 000000000..0c06e975c --- /dev/null +++ b/openapi/components/schemas/v1usersUpdateUser.yaml @@ -0,0 +1,24 @@ +type: object +properties: + external_id: + description: >- + Your application's unique identifier for this organization, used to link + Scalekit with your system. + type: string + examples: + - ext_12345a67b89c + metadata: + description: >- + Custom key-value pairs for storing additional user context. Keys (3-25 + chars), values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - department: engineering + location: nyc-office + user_profile: + description: >- + User's personal information including name, address, and other profile + attributes. + $ref: ./usersUpdateUserProfile.yaml diff --git a/openapi/components/schemas/webauthnAllAcceptedCredentialsOptions.yaml b/openapi/components/schemas/webauthnAllAcceptedCredentialsOptions.yaml new file mode 100644 index 000000000..0476a4776 --- /dev/null +++ b/openapi/components/schemas/webauthnAllAcceptedCredentialsOptions.yaml @@ -0,0 +1,17 @@ +type: object +properties: + all_accepted_credential_ids: + description: List of credential IDs the user can authenticate with + type: array + items: + type: string + rp_id: + description: Relying Party ID for credential operations + type: string + examples: + - example.com + user_id: + description: User ID for credential verification + type: string + examples: + - user_xyz789 diff --git a/openapi/components/schemas/webauthnDeleteCredentialResponse.yaml b/openapi/components/schemas/webauthnDeleteCredentialResponse.yaml new file mode 100644 index 000000000..6c58e84eb --- /dev/null +++ b/openapi/components/schemas/webauthnDeleteCredentialResponse.yaml @@ -0,0 +1,10 @@ +type: object +properties: + success: + description: Whether the credential was successfully deleted + type: boolean + examples: + - true + unknown_credential_options: + description: Options for handling unknown credentials in client applications + $ref: ./webauthnUnknownCredentialOptions.yaml diff --git a/openapi/components/schemas/webauthnListCredentialsResponse.yaml b/openapi/components/schemas/webauthnListCredentialsResponse.yaml new file mode 100644 index 000000000..8b2549bdb --- /dev/null +++ b/openapi/components/schemas/webauthnListCredentialsResponse.yaml @@ -0,0 +1,11 @@ +type: object +properties: + all_accepted_credentials_options: + description: Options including RP ID and all accepted credential IDs for authentication + $ref: ./webauthnAllAcceptedCredentialsOptions.yaml + credentials: + description: All passkeys registered for the user + type: array + items: + type: object + $ref: ./webauthnWebAuthnCredential.yaml diff --git a/openapi/components/schemas/webauthnUnknownCredentialOptions.yaml b/openapi/components/schemas/webauthnUnknownCredentialOptions.yaml new file mode 100644 index 000000000..fa5a4866a --- /dev/null +++ b/openapi/components/schemas/webauthnUnknownCredentialOptions.yaml @@ -0,0 +1,12 @@ +type: object +properties: + credential_id: + description: The deleted credential ID + type: string + examples: + - cred_abc123 + rp_id: + description: The RP ID for this credential + type: string + examples: + - example.com diff --git a/openapi/components/schemas/webauthnUpdateCredentialResponse.yaml b/openapi/components/schemas/webauthnUpdateCredentialResponse.yaml new file mode 100644 index 000000000..76c5d5da1 --- /dev/null +++ b/openapi/components/schemas/webauthnUpdateCredentialResponse.yaml @@ -0,0 +1,5 @@ +type: object +properties: + credential: + description: The updated credential with new display name + $ref: ./webauthnWebAuthnCredential.yaml diff --git a/openapi/components/schemas/webauthnWebAuthnCredential.yaml b/openapi/components/schemas/webauthnWebAuthnCredential.yaml new file mode 100644 index 000000000..3cd332220 --- /dev/null +++ b/openapi/components/schemas/webauthnWebAuthnCredential.yaml @@ -0,0 +1,55 @@ +type: object +properties: + attestation_type: + description: 'Type of attestation: "none", "indirect", or "direct"' + type: string + examples: + - direct + authenticator: + description: Authenticator information including model and name + $ref: ./WebAuthnCredentialAuthenticator.yaml + authenticator_flags: + description: Flags indicating authenticator capabilities + $ref: ./WebAuthnCredentialAuthenticatorFlags.yaml + client_info: + description: Geographic and network information from registration + $ref: ./WebAuthnCredentialClientInfo.yaml + created_at: + description: Timestamp when the credential was created + type: string + format: date-time + examples: + - '2025-02-15T06:23:44.560000Z' + credential_id: + description: The actual credential ID bytes from the authenticator + type: string + contentEncoding: base64 + display_name: + description: Optional user-friendly name for this passkey + type: string + examples: + - My Yubikey + id: + description: Credential unique identifier + type: string + examples: + - cred_abc123 + transports: + description: Supported transports for this credential + type: array + items: + type: string + updated_at: + description: Timestamp of last update + type: string + format: date-time + examples: + - '2025-02-15T06:23:44.560000Z' + user_agent: + description: Browser and device information from registration + $ref: ./WebAuthnCredentialUserAgent.yaml + user_id: + description: User ID this credential belongs to + type: string + examples: + - user_xyz789 diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml new file mode 100644 index 000000000..f6c93e200 --- /dev/null +++ b/openapi/openapi.yaml @@ -0,0 +1,409 @@ +info: + description: "# Overview\n\nThe Scalekit API is a RESTful API that enables you to manage organizations, users, and authentication settings. All requests must use HTTPS.\nAll API requests use the following base URLs:\n\n```\nhttps://{your-subdomain}.scalekit.dev (Development)\nhttps://{your-subdomain}.scalekit.com (Production)\nhttps://auth.yourapp.com (Custom domain)\n```\n\nScalekit operates two separate environments: Development and Production. Resources cannot be moved between environments.\n\n## Quickstart\n\nThe Scalekit API uses OAuth 2.0 Client Credentials for authentication.\n\nCopy your API credentials from the Scalekit dashboard's API Config section and set them as environment variables.\n\n```sh\nSCALEKIT_ENVIRONMENT_URL=''\nSCALEKIT_CLIENT_ID=''\nSCALEKIT_CLIENT_SECRET=''\n```\n\nGetting an access token\n\n1. Get your credentials from the [Scalekit Dashboard](https://app.scalekit.com)\n2. Request an access token:\n\n```sh\ncurl https:///oauth/token \\\n -X POST \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d 'client_id={client_id}' \\\n -d 'client_secret={client_secret}' \\\n -d 'grant_type=client_credentials'\n```\n\n3. Use the access token in API requests:\n\n```sh\ncurl https:///api/v1/organizations \\\n -H 'Content-Type: application/json' \\\n -H 'Authorization: Bearer {access_token}'\n```\n\nThe response includes an access token:\n\n```json\n{\n\t\"access_token\": \"eyJhbGciOiJSUzI1NiIsImtpZCI6InNua181Ok4OTEyMjU2NiIsInR5cCI6IkpXVCJ9...\",\n\t\"token_type\": \"Bearer\",\n\t\"expires_in\": 86399,\n\t\"scope\": \"openid\"\n}\n```\n\n## SDKs\n\nScalekit provides official SDKs for multiple programming languages. Check the changelog at GitHub repositories for the latest updates.\n\n### Node.js\n\n```sh\nnpm install @scalekit-sdk/node\n```\n\nCreate a new Scalekit client instance after initializing the environment variables\n\n```js\nimport { Scalekit } from \"@scalekit-sdk/node\";\n\nexport let scalekit = new Scalekit(\n\tprocess.env.SCALEKIT_ENVIRONMENT_URL,\n\tprocess.env.SCALEKIT_CLIENT_ID,\n\tprocess.env.SCALEKIT_CLIENT_SECRET\n);\n```\n\n[See the Node SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-node/releases)\n\n### Python\n\n```sh\npip install scalekit-sdk-python\n```\n\nCreate a new Scalekit client instance after initializing the environment variables.\n\n```py\nfrom scalekit import ScalekitClient\nimport os\n\nscalekit_client = ScalekitClient(\n os.environ.get('SCALEKIT_ENVIRONMENT_URL'),\n os.environ.get('SCALEKIT_CLIENT_ID'),\n os.environ.get('SCALEKIT_CLIENT_SECRET')\n)\n```\n\n[See the Python SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-python/releases)\n\n### Go\n\n```sh\ngo get -u github.com/scalekit-inc/scalekit-sdk-go\n```\n\nCreate a new Scalekit client instance after initializing the environment variables.\n\n```go\npackage main\n\nimport (\n \"os\"\n \"github.com/scalekit-inc/scalekit-sdk-go\"\n)\n\nscalekitClient := scalekit.NewScalekitClient(\n os.Getenv(\"SCALEKIT_ENVIRONMENT_URL\"),\n os.Getenv(\"SCALEKIT_CLIENT_ID\"),\n os.Getenv(\"SCALEKIT_CLIENT_SECRET\"),\n)\n```\n\n[See the Go SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-go/releases)\n\n### Java\n\n```gradle\n/* Gradle users - add the following to your dependencies in build file */\nimplementation \"com.scalekit:scalekit-sdk-java:2.0.11\"\n```\n\n```xml\n\n\n com.scalekit\n scalekit-sdk-java\n 2.0.11\n\n```\n\n[See the Java SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-java/releases)\n\n### Error handling\n\nThe API uses standard HTTP status codes:\n\n| Code | Description |\n| ----------- | -------------------- |\n| 200/201 | Success |\n| 400 | Invalid request |\n| 401 | Authentication error |\n| 404 | Resource not found |\n| 429 | Rate limit exceeded |\n| 500/501/504 | Server error |\n\nError responses include detailed information:\n\n```json\n{\n\t\"code\": 16,\n\t\"message\": \"Token empty\",\n\t\"details\": [\n\t\t{\n\t\t\t\"@type\": \"type.googleapis.com/scalekit.v1.errdetails.ErrorInfo\",\n\t\t\t\"error_code\": \"UNAUTHENTICATED\"\n\t\t}\n\t]\n}\n```\n" + title: Scalekit APIs + contact: + name: Scalekit Inc + url: https://scalekit.com + email: support@scalekit.com + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0 + version: 1.0.0 + x-scalar-sdk-installation: + - lang: shell + description: >- + Set up OAuth 2.0 Client Credentials authentication to access Scalekit + APIs. Includes credential configuration, token exchange, and + authenticated API request examples. + source: > + + # 1. Obtain API Credentials + + # Get your credentials from the Scalekit dashboard + + export SCALEKIT_ENVIRONMENT_URL="https://your-org.scalekit.dev" # Your + Scalekit environment URL + + export SCALEKIT_CLIENT_ID="your_client_id" # Your + client ID + + export SCALEKIT_CLIENT_SECRET="your_client_secret" # Your + client secret + + + # 2. Exchange client credentials an OAuth 2.0 access token + + TOKEN_RESPONSE=$(curl -s -X POST + "${SCALEKIT_ENVIRONMENT_URL}/oauth/token" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "client_id=${SCALEKIT_CLIENT_ID}" \ + -d "client_secret=${SCALEKIT_CLIENT_SECRET}" \ + -d "grant_type=client_credentials") + + # 3. Make Authenticated API Requests + + curl -X GET "${SCALEKIT_ENVIRONMENT_URL}/api/v1/organizations" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${ACCESS_TOKEN}" \ + -H "Accept: application/json" +paths: + /api/v1/connected_accounts: + $ref: paths/api_v1_connected_accounts.yaml + /api/v1/connected_accounts/auth: + $ref: paths/api_v1_connected_accounts_auth.yaml + /api/v1/connected_accounts/details: + $ref: paths/api_v1_connected_accounts_details.yaml + /api/v1/connected_accounts/magic_link: + $ref: paths/api_v1_connected_accounts_magic_link.yaml + /api/v1/connected_accounts/user/verify: + $ref: paths/api_v1_connected_accounts_user_verify.yaml + /api/v1/connected_accounts:delete: + $ref: paths/api_v1_connected_accounts:delete.yaml + /api/v1/connected_accounts:search: + $ref: paths/api_v1_connected_accounts:search.yaml + /api/v1/connections: + $ref: paths/api_v1_connections.yaml + /api/v1/execute_tool: + $ref: paths/api_v1_execute_tool.yaml + /api/v1/invites/organizations/{organization_id}/users/{id}/resend: + $ref: >- + paths/api_v1_invites_organizations_{organization_id}_users_{id}_resend.yaml + /api/v1/memberships/organizations/{organization_id}/users/{id}: + $ref: paths/api_v1_memberships_organizations_{organization_id}_users_{id}.yaml + /api/v1/organizations: + $ref: paths/api_v1_organizations.yaml + /api/v1/organizations/{id}: + $ref: paths/api_v1_organizations_{id}.yaml + /api/v1/organizations/{id}/portal_links: + $ref: paths/api_v1_organizations_{id}_portal_links.yaml + /api/v1/organizations/{id}/settings: + $ref: paths/api_v1_organizations_{id}_settings.yaml + /api/v1/organizations/{org_id}/roles: + $ref: paths/api_v1_organizations_{org_id}_roles.yaml + /api/v1/organizations/{org_id}/roles/{role_name}: + $ref: paths/api_v1_organizations_{org_id}_roles_{role_name}.yaml + /api/v1/organizations/{org_id}/roles:set_defaults: + $ref: paths/api_v1_organizations_{org_id}_roles:set_defaults.yaml + /api/v1/organizations/{organization_id}/clients: + $ref: paths/api_v1_organizations_{organization_id}_clients.yaml + /api/v1/organizations/{organization_id}/clients/{client_id}: + $ref: paths/api_v1_organizations_{organization_id}_clients_{client_id}.yaml + /api/v1/organizations/{organization_id}/clients/{client_id}/secrets: + $ref: >- + paths/api_v1_organizations_{organization_id}_clients_{client_id}_secrets.yaml + /api/v1/organizations/{organization_id}/clients/{client_id}/secrets/{secret_id}: + $ref: >- + paths/api_v1_organizations_{organization_id}_clients_{client_id}_secrets_{secret_id}.yaml + /api/v1/organizations/{organization_id}/connections/{id}: + $ref: paths/api_v1_organizations_{organization_id}_connections_{id}.yaml + /api/v1/organizations/{organization_id}/connections/{id}:disable: + $ref: paths/api_v1_organizations_{organization_id}_connections_{id}:disable.yaml + /api/v1/organizations/{organization_id}/connections/{id}:enable: + $ref: paths/api_v1_organizations_{organization_id}_connections_{id}:enable.yaml + /api/v1/organizations/{organization_id}/directories: + $ref: paths/api_v1_organizations_{organization_id}_directories.yaml + /api/v1/organizations/{organization_id}/directories/{directory_id}/groups: + $ref: >- + paths/api_v1_organizations_{organization_id}_directories_{directory_id}_groups.yaml + /api/v1/organizations/{organization_id}/directories/{directory_id}/users: + $ref: >- + paths/api_v1_organizations_{organization_id}_directories_{directory_id}_users.yaml + /api/v1/organizations/{organization_id}/directories/{id}: + $ref: paths/api_v1_organizations_{organization_id}_directories_{id}.yaml + /api/v1/organizations/{organization_id}/directories/{id}:disable: + $ref: paths/api_v1_organizations_{organization_id}_directories_{id}:disable.yaml + /api/v1/organizations/{organization_id}/directories/{id}:enable: + $ref: paths/api_v1_organizations_{organization_id}_directories_{id}:enable.yaml + /api/v1/organizations/{organization_id}/domains: + $ref: paths/api_v1_organizations_{organization_id}_domains.yaml + /api/v1/organizations/{organization_id}/domains/{id}: + $ref: paths/api_v1_organizations_{organization_id}_domains_{id}.yaml + /api/v1/organizations/{organization_id}/session-policy: + $ref: paths/api_v1_organizations_{organization_id}_session-policy.yaml + /api/v1/organizations/{organization_id}/settings/usermanagement: + $ref: paths/api_v1_organizations_{organization_id}_settings_usermanagement.yaml + /api/v1/organizations/{organization_id}/users: + $ref: paths/api_v1_organizations_{organization_id}_users.yaml + /api/v1/organizations/{organization_id}/users/{user_id}/permissions: + $ref: >- + paths/api_v1_organizations_{organization_id}_users_{user_id}_permissions.yaml + /api/v1/organizations/{organization_id}/users/{user_id}/roles: + $ref: paths/api_v1_organizations_{organization_id}_users_{user_id}_roles.yaml + /api/v1/organizations/{organization_id}/users:search: + $ref: paths/api_v1_organizations_{organization_id}_users:search.yaml + /api/v1/organizations:external/{external_id}: + $ref: paths/api_v1_organizations:external_{external_id}.yaml + /api/v1/passwordless/email/resend: + $ref: paths/api_v1_passwordless_email_resend.yaml + /api/v1/passwordless/email/send: + $ref: paths/api_v1_passwordless_email_send.yaml + /api/v1/passwordless/email/verify: + $ref: paths/api_v1_passwordless_email_verify.yaml + /api/v1/permissions: + $ref: paths/api_v1_permissions.yaml + /api/v1/permissions/{permission_name}: + $ref: paths/api_v1_permissions_{permission_name}.yaml + /api/v1/roles: + $ref: paths/api_v1_roles.yaml + /api/v1/roles/default: + $ref: paths/api_v1_roles_default.yaml + /api/v1/roles/{role_name}: + $ref: paths/api_v1_roles_{role_name}.yaml + /api/v1/roles/{role_name}/dependents: + $ref: paths/api_v1_roles_{role_name}_dependents.yaml + /api/v1/roles/{role_name}/permissions: + $ref: paths/api_v1_roles_{role_name}_permissions.yaml + /api/v1/roles/{role_name}/permissions/{permission_name}: + $ref: paths/api_v1_roles_{role_name}_permissions_{permission_name}.yaml + /api/v1/roles/{role_name}/permissions:all: + $ref: paths/api_v1_roles_{role_name}_permissions:all.yaml + /api/v1/roles/{role_name}/users:count: + $ref: paths/api_v1_roles_{role_name}_users:count.yaml + /api/v1/roles:set_defaults: + $ref: paths/api_v1_roles:set_defaults.yaml + /api/v1/sessions/{session_id}: + $ref: paths/api_v1_sessions_{session_id}.yaml + /api/v1/sessions/{session_id}/revoke: + $ref: paths/api_v1_sessions_{session_id}_revoke.yaml + /api/v1/users: + $ref: paths/api_v1_users.yaml + /api/v1/users/{id}: + $ref: paths/api_v1_users_{id}.yaml + /api/v1/users/{user_id}/sessions: + $ref: paths/api_v1_users_{user_id}_sessions.yaml + /api/v1/users/{user_id}/sessions/revoke: + $ref: paths/api_v1_users_{user_id}_sessions_revoke.yaml + /api/v1/users:search: + $ref: paths/api_v1_users:search.yaml + /api/v1/webauthn/credentials: + $ref: paths/api_v1_webauthn_credentials.yaml + /api/v1/webauthn/credentials/{credential_id}: + $ref: paths/api_v1_webauthn_credentials_{credential_id}.yaml +tags: + - description: > + Organization represents a customer or a tenant of your product. This is + the top level entity and all resources are mapped to this Organization + object. Each organization is uniquely identified by `organization_id`. + + + + name: Organizations + - description: >- + Permission management for defining and controlling access to system + resources. Create, retrieve, update, and delete granular permissions that + represent specific actions users can perform. Permissions are the building + blocks of role-based access control (RBAC) and can be assigned to roles to + grant users the ability to perform specific operations. Use this service + to define custom permissions for your application's unique access control + requirements. + name: Permissions + - description: >- + Comprehensive user management operations including user lifecycle, + organization memberships, and invitation workflows. This service provides + endpoints for creating, retrieving, updating, and deleting user accounts + across your Scalekit environment. It supports both individual user + operations and bulk operations for user administration, including user + search, pagination, and metadata management. The service also handles user + invitations and organization membership management. + name: Users + - description: >- + Manage enterprise connections for your Scalekit environment. This service + provides endpoints for retrieving, and updating connections. + name: Connections + - description: >- + Directory management for viewing and controlling external identity + provider connections in your Scalekit environment. This service provides + endpoints for retrieving directory information, listing directories and + their contents, and enabling or disabling directory synchronization. + name: Directory + - description: >- + Role-based access control (RBAC) for defining and managing permissions in + an environment. Create and update custom roles with explicit permissions, + model role hierarchies through inheritance, view dependent roles, manage + role-permission assignments, and list roles and permissions. Also provides + a utility to count users assigned to a role. + name: Roles + - description: >- + Comprehensive session management for user authentication and + authorization. This service provides endpoints for retrieving session + details, managing user sessions across devices, revoking individual + sessions, and terminating all active sessions for a user. It supports + session auditing, device tracking, and security monitoring with detailed + session metadata including device information, IP geolocation, and + activity timestamps. + name: Sessions + - description: > + Manage organization-level domains. Scalekit supports two domain types: + + + - ORGANIZATION_DOMAIN: Used for SSO domain discovery. When a user signs in + with a matching email domain, Scalekit routes them to the organization’s + SSO provider and enforces SSO. + + - ALLOWED_EMAIL_DOMAIN: Used to mark trusted email domains for an + organization. When a user signs in or signs up with a matching domain, + Scalekit suggests the organization in the organization switcher + (authentication-method agnostic). + name: Domains + - description: >- + Endpoints for managing API client applications. API clients enable secure, + automated interactions between software systems without human + intervention. Each client is uniquely identified by a `client_id` and can + be configured with authentication settings, redirect URIs, and security + parameters. Use these endpoints to create, manage, and configure API + clients for your API clients. + name: API Auth + externalDocs: + url: https://docs.scalekit.com/m2m/overview + - description: >- + Endpoints for sending and verifying passwordless authentication emails. + These APIs allow users to authenticate without passwords by receiving a + verification code or magic link in their email. + name: Magic link & OTP + - description: Endpoints for passkey-based authentication using WebAuthn/FIDO2 standards. + name: Passkeys + - description: >- + Manage connected accounts for third-party integrations and OAuth + connections. Connected accounts represent authenticated access to external + services like Google, Notion, Slack, and other applications. + name: Connected Accounts +externalDocs: + description: Scalekit Docs + url: https://docs.scalekit.com/ +openapi: 3.1.1 +servers: + - url: https://$SCALEKIT_ENVIRONMENT_URL +components: + securitySchemes: + oauth2: + type: oauth2 + flows: + clientCredentials: + tokenUrl: https://$SCALEKIT_ENVIRONMENT_URL/oauth/token + scopes: + '': No scope required for client credentials flow +x-scalar-environments: + production: + variables: + SCALEKIT_ENVIRONMENT_URL: + default: https://$SCALEKIT_ENVIRONMENT_URL + description: yourapp.scalekit.com + staging: + variables: + SCALEKIT_ENVIRONMENT_URL: + default: https://$SCALEKIT_ENVIRONMENT_URL + description: yourapp.scalekit.dev +x-scalar-active-environment: staging +security: + - oauth2: [] +webhooks: + organization.created: + $ref: webhooks/organization.created.yaml + organization.updated: + $ref: webhooks/organization.updated.yaml + organization.deleted: + $ref: webhooks/organization.deleted.yaml + user.signup: + $ref: webhooks/user.signup.yaml + user.login: + $ref: webhooks/user.login.yaml + user.logout: + $ref: webhooks/user.logout.yaml + user.organization_invitation: + $ref: webhooks/user.organization_invitation.yaml + user.organization_membership_created: + $ref: webhooks/user.organization_membership_created.yaml + user.organization_membership_deleted: + $ref: webhooks/user.organization_membership_deleted.yaml + user.organization_membership_updated: + $ref: webhooks/user.organization_membership_updated.yaml + organization.directory_enabled: + $ref: webhooks/organization.directory_enabled.yaml + organization.directory_disabled: + $ref: webhooks/organization.directory_disabled.yaml + organization.directory.user_created: + $ref: webhooks/organization.directory.user_created.yaml + organization.directory.user_updated: + $ref: webhooks/organization.directory.user_updated.yaml + organization.directory.user_deleted: + $ref: webhooks/organization.directory.user_deleted.yaml + organization.directory.group_created: + $ref: webhooks/organization.directory.group_created.yaml + organization.directory.group_updated: + $ref: webhooks/organization.directory.group_updated.yaml + organization.directory.group_deleted: + $ref: webhooks/organization.directory.group_deleted.yaml + organization.sso_created: + $ref: webhooks/organization.sso_created.yaml + organization.sso_enabled: + $ref: webhooks/organization.sso_enabled.yaml + organization.sso_disabled: + $ref: webhooks/organization.sso_disabled.yaml + organization.sso_deleted: + $ref: webhooks/organization.sso_deleted.yaml + role.created: + $ref: webhooks/role.created.yaml + role.updated: + $ref: webhooks/role.updated.yaml + role.deleted: + $ref: webhooks/role.deleted.yaml + permission.created: + $ref: webhooks/permission.created.yaml + permission.updated: + $ref: webhooks/permission.updated.yaml + permission.deleted: + $ref: webhooks/permission.deleted.yaml + connected_account.created: + $ref: webhooks/connected_account.created.yaml + connected_account.updated: + $ref: webhooks/connected_account.updated.yaml + connected_account.deleted: + $ref: webhooks/connected_account.deleted.yaml + connected_account.magic_link_generated: + $ref: webhooks/connected_account.magic_link_generated.yaml + connected_account.oauth_tokens_fetched: + $ref: webhooks/connected_account.oauth_tokens_fetched.yaml + connected_account.token_refresh_succeeded: + $ref: webhooks/connected_account.token_refresh_succeeded.yaml + connected_account.token_refresh_failed: + $ref: webhooks/connected_account.token_refresh_failed.yaml + connected_account.oauth_succeeded: + $ref: webhooks/connected_account.oauth_succeeded.yaml diff --git a/openapi/paths/api_v1_connected_accounts.yaml b/openapi/paths/api_v1_connected_accounts.yaml new file mode 100644 index 000000000..825700f09 --- /dev/null +++ b/openapi/paths/api_v1_connected_accounts.yaml @@ -0,0 +1,182 @@ +get: + description: >- + Retrieves a paginated list of connected accounts for third-party + integrations. Filter by organization, user, connector type, provider, or + identifier. Returns OAuth tokens, API keys, and connection status for each + account. Use pagination tokens to navigate through large result sets. + tags: + - Connected Accounts + summary: List connected accounts + operationId: ConnectedAccountService_ListConnectedAccounts + parameters: + - schema: + type: string + description: >- + Filter by organization ID. Returns only connected accounts associated + with this organization. + name: organization_id + in: query + - schema: + type: string + description: >- + Filter by user ID. Returns only connected accounts associated with this + user. + name: user_id + in: query + - schema: + type: string + description: >- + Filter by connector type (e.g., 'notion', 'slack', 'google'). + Alphanumeric characters, spaces, hyphens, underscores, and colons are + allowed. + name: connector + in: query + - schema: + type: string + description: >- + Filter by account identifier. The unique identifier for the connected + account within the third-party service (e.g., email address, workspace + ID). + name: identifier + in: query + - schema: + type: string + description: >- + Filter by OAuth provider. The authentication provider name such as + 'google', 'microsoft', 'github', etc. + name: provider + in: query + - schema: + type: integer + format: int64 + description: >- + Maximum number of connected accounts to return per page. Must be between + 0 and 100. Default is typically 10. + name: page_size + in: query + - schema: + type: string + description: >- + Pagination token from a previous response. Use the next_page_token value + from ListConnectedAccountsResponse to fetch the next page. + name: page_token + in: query + - schema: + type: string + description: >- + Text search query to filter connected accounts by name, identifier, or + other searchable fields. Case-insensitive. + name: query + in: query + responses: + '200': + description: >- + Successfully retrieved the list of connected accounts with their + authentication details and status + content: + application/json: + schema: + $ref: >- + ../components/schemas/connected_accountsListConnectedAccountsResponse.yaml + '400': + description: >- + Invalid request - occurs when query parameters are malformed or + validation fails + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} +put: + description: >- + Updates authentication credentials and configuration for an existing + connected account. Modify OAuth tokens, refresh tokens, access scopes, or + API configuration settings. Specify the account by ID, or by combination of + organization/user, connector, and identifier. Returns the updated account + with new token expiry and status information. + tags: + - Connected Accounts + summary: Update connected account credentials + operationId: ConnectedAccountService_UpdateConnectedAccount + responses: + '200': + description: >- + Connected account updated successfully with new credentials or + configuration + content: + application/json: + schema: + $ref: >- + ../components/schemas/connected_accountsUpdateConnectedAccountResponse.yaml + '400': + description: >- + Invalid request - missing required fields, invalid authorization + details, or validation failed + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + '404': + description: Connected account not found - the specified account does not exist + content: + application/json: + schema: {} + requestBody: + content: + application/json: + schema: + $ref: >- + ../components/schemas/connected_accountsUpdateConnectedAccountRequest.yaml + required: true +post: + description: >- + Creates a new connected account with OAuth tokens or API credentials for + third-party service integration. Supply authorization details including + access tokens, refresh tokens, scopes, and optional API configuration. The + account can be scoped to an organization or user. Returns the created + account with its unique identifier and authentication status. + tags: + - Connected Accounts + summary: Create a connected account + operationId: ConnectedAccountService_CreateConnectedAccount + responses: + '201': + description: >- + Connected account created successfully with authentication credentials + stored securely + content: + application/json: + schema: + $ref: >- + ../components/schemas/connected_accountsCreateConnectedAccountResponse.yaml + '400': + description: >- + Invalid request - missing required fields, invalid authorization + details, or validation failed + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + '409': + description: Conflict - connected account with the same identifier already exists + content: + application/json: + schema: {} + requestBody: + content: + application/json: + schema: + $ref: >- + ../components/schemas/connected_accountsCreateConnectedAccountRequest.yaml + required: true diff --git a/openapi/paths/api_v1_connected_accounts:delete.yaml b/openapi/paths/api_v1_connected_accounts:delete.yaml new file mode 100644 index 000000000..25e5f45e7 --- /dev/null +++ b/openapi/paths/api_v1_connected_accounts:delete.yaml @@ -0,0 +1,38 @@ +post: + description: >- + Permanently removes a connected account and revokes all associated + authentication credentials. Identify the account by ID, or by combination of + organization/user, connector, and identifier. This action cannot be undone. + All OAuth tokens and API keys for this account will be invalidated. + tags: + - Connected Accounts + summary: Delete a connected account + operationId: ConnectedAccountService_DeleteConnectedAccount + responses: + '200': + description: Connected account deleted successfully and all credentials revoked + content: + application/json: + schema: {} + '400': + description: Invalid request - malformed parameters or validation failed + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + '404': + description: Connected account not found - the specified account does not exist + content: + application/json: + schema: {} + requestBody: + content: + application/json: + schema: + $ref: >- + ../components/schemas/connected_accountsDeleteConnectedAccountRequest.yaml + required: true diff --git a/openapi/paths/api_v1_connected_accounts:search.yaml b/openapi/paths/api_v1_connected_accounts:search.yaml new file mode 100644 index 000000000..4bfaa205b --- /dev/null +++ b/openapi/paths/api_v1_connected_accounts:search.yaml @@ -0,0 +1,60 @@ +get: + description: >- + Search for connected accounts in your environment using a text query that + matches against identifiers, providers, or connectors. The search performs + case-insensitive matching across account details. Returns paginated results + with account status and authentication type information. + tags: + - Connected Accounts + summary: Search connected accounts + operationId: ConnectedAccountService_SearchConnectedAccounts + parameters: + - schema: + type: string + description: >- + Search term to match against connected account identifiers, providers, + or connectors. Must be at least 3 characters. Case insensitive. + name: query + in: query + - schema: + type: integer + format: int64 + description: >- + Maximum number of connected accounts to return per page. Value must be + between 1 and 30. + name: page_size + in: query + - schema: + type: string + description: >- + Token from a previous response for pagination. Provide this to retrieve + the next page of results. + name: page_token + in: query + - schema: + type: string + description: Connection ID to filter connected accounts + name: connection_id + in: query + responses: + '200': + description: >- + Successfully retrieved matching connected accounts with pagination + support + content: + application/json: + schema: + $ref: >- + ../components/schemas/connected_accountsSearchConnectedAccountsResponse.yaml + '400': + description: >- + Invalid request - query parameter is too short (minimum 3 characters) or + validation failed + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} diff --git a/openapi/paths/api_v1_connected_accounts_auth.yaml b/openapi/paths/api_v1_connected_accounts_auth.yaml new file mode 100644 index 000000000..7f84ee2ea --- /dev/null +++ b/openapi/paths/api_v1_connected_accounts_auth.yaml @@ -0,0 +1,66 @@ +get: + description: >- + Retrieves complete authentication details for a connected account including + OAuth tokens, refresh tokens, scopes, and API configuration. Query by + account ID or by combination of organization/user, connector, and + identifier. Returns sensitive credential information - use appropriate + access controls. + tags: + - Connected Accounts + summary: Get connected account auth credentials + operationId: ConnectedAccountService_GetConnectedAccountAuth + parameters: + - schema: + type: string + description: Organization ID for the connector + name: organization_id + in: query + - schema: + type: string + description: User ID for the connector + name: user_id + in: query + - schema: + type: string + description: >- + Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric + characters, spaces, hyphens, underscores, and colons are allowed. + name: connector + in: query + - schema: + type: string + description: >- + The unique identifier for the connected account within the third-party + service (e.g., email address, user ID, workspace identifier). + name: identifier + in: query + - schema: + type: string + description: Unique identifier for the connected account + name: id + in: query + responses: + '200': + description: >- + Successfully retrieved connected account with full authentication + details + content: + application/json: + schema: + $ref: >- + ../components/schemas/connected_accountsGetConnectedAccountByIdentifierResponse.yaml + '400': + description: Invalid request - missing required query parameters + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + '404': + description: Connected account not found - no account matches the specified criteria + content: + application/json: + schema: {} diff --git a/openapi/paths/api_v1_connected_accounts_details.yaml b/openapi/paths/api_v1_connected_accounts_details.yaml new file mode 100644 index 000000000..405cbd5c3 --- /dev/null +++ b/openapi/paths/api_v1_connected_accounts_details.yaml @@ -0,0 +1,63 @@ +get: + description: >- + Returns metadata for a connected account including status, connector type, + provider, and configuration without exposing stored authorization + credentials. Look up by account ID, or by a combination of organization (or + user), connector, and external identifier. + tags: + - Connected Accounts + summary: Get connected account metadata + operationId: ConnectedAccountService_GetConnectedAccountDetails + parameters: + - schema: + type: string + description: Organization ID for the connector + name: organization_id + in: query + - schema: + type: string + description: User ID for the connector + name: user_id + in: query + - schema: + type: string + description: >- + Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric + characters, spaces, hyphens, underscores, and colons are allowed. + name: connector + in: query + - schema: + type: string + description: >- + The unique identifier for the connected account within the third-party + service (e.g., email address, user ID, workspace identifier). + name: identifier + in: query + - schema: + type: string + description: Unique identifier for the connected account + name: id + in: query + responses: + '200': + description: Successfully retrieved connected account details + content: + application/json: + schema: + $ref: >- + ../components/schemas/connected_accountsGetConnectedAccountByIdentifierResponse.yaml + '400': + description: Invalid request - missing required query parameters + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + '404': + description: Connected account not found - no account matches the specified criteria + content: + application/json: + schema: {} diff --git a/openapi/paths/api_v1_connected_accounts_magic_link.yaml b/openapi/paths/api_v1_connected_accounts_magic_link.yaml new file mode 100644 index 000000000..d232a26fb --- /dev/null +++ b/openapi/paths/api_v1_connected_accounts_magic_link.yaml @@ -0,0 +1,35 @@ +post: + description: >- + Creates a time-limited magic link for connecting or re-authorizing a + third-party account. The link directs users to the OAuth authorization flow + for the specified connector. Returns the generated link URL and expiration + timestamp. Links typically expire after a short duration for security. + tags: + - Connected Accounts + summary: Generate authentication magic link + operationId: ConnectedAccountService_GetMagicLinkForConnectedAccount + responses: + '200': + description: Magic link generated successfully with authorization URL and expiry time + content: + application/json: + schema: + $ref: >- + ../components/schemas/connected_accountsGetMagicLinkForConnectedAccountResponse.yaml + '400': + description: Invalid request - missing required parameters or invalid connector + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + requestBody: + content: + application/json: + schema: + $ref: >- + ../components/schemas/connected_accountsGetMagicLinkForConnectedAccountRequest.yaml + required: true diff --git a/openapi/paths/api_v1_connected_accounts_user_verify.yaml b/openapi/paths/api_v1_connected_accounts_user_verify.yaml new file mode 100644 index 000000000..fd2a56bdc --- /dev/null +++ b/openapi/paths/api_v1_connected_accounts_user_verify.yaml @@ -0,0 +1,48 @@ +post: + description: >- + Confirms the user assertion and activates the connected account after the + user completes third-party OAuth. Called by the B2B app server with + auth_request_id and identifier. Validates that the asserted identifier + matches the one stored on the auth request and promotes pending tokens to + live. + tags: + - Connected Accounts + summary: Verify connected account user + operationId: ConnectedAccountService_VerifyConnectedAccountUser + responses: + '200': + description: Verification successful; connected account is now ACTIVE + content: + application/json: + schema: + $ref: >- + ../components/schemas/connected_accountsVerifyConnectedAccountUserResponse.yaml + '400': + description: Invalid request - missing or malformed fields + content: + application/json: + schema: {} + '401': + description: Unauthorized - invalid or missing access token + content: + application/json: + schema: {} + '403': + description: Forbidden - identifier mismatch + content: + application/json: + schema: {} + '404': + description: >- + Not found - no pending flow for the given auth_request_id or already + consumed + content: + application/json: + schema: {} + requestBody: + content: + application/json: + schema: + $ref: >- + ../components/schemas/connected_accountsVerifyConnectedAccountUserRequest.yaml + required: true diff --git a/openapi/paths/api_v1_connections.yaml b/openapi/paths/api_v1_connections.yaml new file mode 100644 index 000000000..1697626eb --- /dev/null +++ b/openapi/paths/api_v1_connections.yaml @@ -0,0 +1,49 @@ +get: + description: Retrieves a list of connections in the environment + tags: + - Connections + summary: List connections + operationId: ConnectionService_ListConnections + parameters: + - schema: + type: string + description: Filter connections by organization identifier + name: organization_id + in: query + - schema: + type: string + description: Filter connections by email domain associated with the organization + name: domain + in: query + - schema: + type: string + description: >- + Filter connections by status. Use 'all' to include all connections + regardless of status. Default behavior shows only active (completed and + enabled) connections + name: include + in: query + responses: + '200': + description: Successfully retrieved connections + content: + application/json: + schema: + $ref: ../components/schemas/connectionsListConnectionsResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_connections/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_connections/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_connections/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_connections/get.java diff --git a/openapi/paths/api_v1_execute_tool.yaml b/openapi/paths/api_v1_execute_tool.yaml new file mode 100644 index 000000000..30b09fbe0 --- /dev/null +++ b/openapi/paths/api_v1_execute_tool.yaml @@ -0,0 +1,52 @@ +post: + description: >- + Executes a tool action using authentication credentials from a connected + account. Specify the tool by name and provide required parameters as JSON. + The connected account can be identified by ID, or by combination of + organization/user, connector, and identifier. Returns the execution result + data and a unique execution ID for tracking. Use this endpoint to perform + actions like sending emails, creating calendar events, or managing resources + in external services. + tags: + - Connected Accounts + summary: Execute a tool using a connected account + operationId: ToolService_ExecuteTool + responses: + '200': + description: Tool executed successfully with result data and execution ID + content: + application/json: + schema: + $ref: ../components/schemas/toolsExecuteToolResponse.yaml + '400': + description: >- + Invalid request - occurs when tool name is missing, parameters are + malformed, or tool definition validation fails + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + '404': + description: >- + Tool or connected account not found - occurs when the specified tool + name or connected account does not exist + content: + application/json: + schema: {} + '500': + description: >- + Tool execution failed - occurs when the external service returns an + error or the tool encounters a runtime exception + content: + application/json: + schema: {} + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/toolsExecuteToolRequest.yaml + required: true diff --git a/openapi/paths/api_v1_invites_organizations_{organization_id}_users_{id}_resend.yaml b/openapi/paths/api_v1_invites_organizations_{organization_id}_users_{id}_resend.yaml new file mode 100644 index 000000000..d1a124fb0 --- /dev/null +++ b/openapi/paths/api_v1_invites_organizations_{organization_id}_users_{id}_resend.yaml @@ -0,0 +1,80 @@ +patch: + description: >- + Resends an invitation email to a user who has a pending or expired + invitation in the specified organization. If the invitation has expired, a + new invitation will be automatically created and sent. If the invitation is + still valid, a reminder email will be sent instead. Use this endpoint when a + user hasn't responded to their initial invitation and you need to send them + a reminder or when the original invitation has expired. The invitation email + includes a secure magic link that allows the user to complete their account + setup and join the organization. Each resend operation increments the resent + counter. + tags: + - Users + summary: Resend user invitation email + operationId: UserService_ResendInvite + parameters: + - schema: + type: string + description: >- + Unique identifier of the organization containing the pending invitation. + Must start with 'org_' and be 1-32 characters long. + name: organization_id + in: path + required: true + - schema: + type: string + description: >- + System-generated user ID of the user who has a pending invitation. Must + start with 'usr_' and be 19-25 characters long. + name: id + in: path + required: true + responses: + '200': + description: >- + Successfully resent the invitation email. Returns the updated invitation + object with organization ID, user ID, membership status, timestamps, and + resent count. If expired, a new invitation is created; otherwise, the + existing one is resent. + content: + application/json: + schema: + $ref: ../components/schemas/usersResendInviteResponse.yaml + '400': + description: >- + Invalid request — common causes include user ID or organization ID is + invalid, full-stack authentication is disabled, user profile is missing, + invite already accepted, or missing expiry time in user management + settings. + content: + application/json: + schema: + $ref: ../components/schemas/errdetailsErrorInfo.yaml + '404': + description: >- + Resource not found — the specified user, organization, membership, or + invitation could not be found in the specified environment. Verify that + all IDs are correct and that the resources exist before attempting to + resend an invitation. + content: + application/json: + schema: + $ref: ../components/schemas/errdetailsErrorInfo.yaml + '500': + description: >- + Internal server error — an unexpected error occurred while processing + the invitation resend request. This may be due to database connectivity + issues, problems generating the secure magic link, email delivery + service failures, or transaction errors during invitation processing. + Contact support if the problem persists. + content: + application/json: + schema: + $ref: ../components/schemas/errdetailsErrorInfo.yaml + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/UserServiceResendInviteBody.yaml + required: true diff --git a/openapi/paths/api_v1_memberships_organizations_{organization_id}_users_{id}.yaml b/openapi/paths/api_v1_memberships_organizations_{organization_id}_users_{id}.yaml new file mode 100644 index 000000000..2cb2b494b --- /dev/null +++ b/openapi/paths/api_v1_memberships_organizations_{organization_id}_users_{id}.yaml @@ -0,0 +1,165 @@ +post: + description: >- + Adds an existing user to an organization and assigns them specific roles and + permissions. Use this endpoint when you want to grant an existing user + access to a particular organization. You can specify roles, metadata, and + other membership details during the invitation process. + tags: + - Users + summary: Add existing user to organization + operationId: UserService_CreateMembership + parameters: + - schema: + type: string + description: >- + Unique identifier of the target organization. Must start with 'org_' and + be 1-32 characters long. + name: organization_id + in: path + required: true + - schema: + type: string + description: System-generated user ID. Must start with 'usr_' (19-25 characters) + name: id + in: path + required: true + - schema: + type: string + description: >- + External system identifier from connected directories. Must be unique + across the system + name: external_id + in: query + - schema: + type: boolean + description: If true, sends an activation email to the user. Defaults to true. + name: send_invitation_email + in: query + responses: + '201': + description: >- + User successfully added to the organization. Returns details of the + updated membership details + content: + application/json: + schema: + $ref: ../components/schemas/usersCreateMembershipResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_memberships_organizations_{organization_id}_users_{id}/post.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_memberships_organizations_{organization_id}_users_{id}/post.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_memberships_organizations_{organization_id}_users_{id}/post.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_memberships_organizations_{organization_id}_users_{id}/post.java + requestBody: + content: + application/json: + schema: + description: Membership details to create. Required fields must be provided. + required: + - membership + $ref: ../components/schemas/v1usersCreateMembership.yaml + required: true +delete: + description: >- + Removes a user from an organization by user ID or external ID. If the user + has no memberships left and cascade is true, the user is also deleted. This + action is irreversible and may also remove related group memberships. + tags: + - Users + summary: Delete organization membership for user + operationId: UserService_DeleteMembership + parameters: + - schema: + type: string + description: >- + Unique organization identifier. Must start with 'org_' and be 1-32 + characters long + name: organization_id + in: path + required: true + - schema: + type: string + description: System-generated user ID. Must start with 'usr_' (19-25 characters) + name: id + in: path + required: true + - schema: + type: string + description: >- + External system identifier from connected directories. Must match + existing records + name: external_id + in: query + responses: + '200': + description: User successfully marked for deletion. No content returned + content: + application/json: + schema: {} + x-codeSamples: + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_memberships_organizations_{organization_id}_users_{id}/delete.py +patch: + description: >- + Updates a user's membership details within an organization by user ID or + external ID. You can update roles and membership metadata. + tags: + - Users + summary: Update organization membership for user + operationId: UserService_UpdateMembership + parameters: + - schema: + type: string + description: >- + Unique identifier of the organization containing the membership. Must + start with 'org_' and be 1-32 characters long. + name: organization_id + in: path + required: true + - schema: + type: string + description: >- + System-generated user ID. Must start with 'usr_' and be 19-25 characters + long. + name: id + in: path + required: true + - schema: + type: string + description: Your application's unique identifier for this user. + name: external_id + in: query + responses: + '200': + description: Membership updated successfully. Returns the updated user object. + content: + application/json: + schema: + $ref: ../components/schemas/usersUpdateMembershipResponse.yaml + requestBody: + content: + application/json: + schema: + description: Membership fields to update. Only specified fields will be modified. + $ref: ../components/schemas/v1usersUpdateMembership.yaml + examples: + - role: admin + required: true diff --git a/openapi/paths/api_v1_organizations.yaml b/openapi/paths/api_v1_organizations.yaml new file mode 100644 index 000000000..bd0fee94d --- /dev/null +++ b/openapi/paths/api_v1_organizations.yaml @@ -0,0 +1,105 @@ +get: + description: >- + Retrieve a paginated list of organizations within your environment. The + response includes a `page_token` that can be used to access subsequent pages + of results. + tags: + - Organizations + summary: List organizations + operationId: OrganizationService_ListOrganization + parameters: + - schema: + type: integer + format: int64 + description: >- + Maximum number of organizations to return per page. Must be between 10 + and 100 + name: page_size + in: query + - schema: + type: string + description: >- + Pagination token from the previous response. Use to retrieve the next + page of organizations + name: page_token + in: query + - schema: + type: string + description: >- + Your application's unique identifier for this organization, used to link + Scalekit with your system + name: external_id + in: query + responses: + '200': + description: Successfully retrieved the list of organizations + content: + application/json: + schema: + $ref: ../components/schemas/organizationsListOrganizationsResponse.yaml + '400': + description: Invalid page token + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_organizations/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_organizations/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_organizations/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_organizations/get.java +post: + description: >- + Creates a new organization in your environment. Use this endpoint to add a + new tenant that can be configured with various settings and metadata + tags: + - Organizations + summary: Create an organization + operationId: OrganizationService_CreateOrganization + responses: + '201': + description: >- + Returns the newly created organization with its unique identifier and + settings + content: + application/json: + schema: + $ref: ../components/schemas/organizationsCreateOrganizationResponse.yaml + x-badges: + - name: '' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_organizations/post.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_organizations/post.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_organizations/post.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_organizations/post.java + requestBody: + content: + application/json: + schema: + description: Required parameters for creating a new organization + $ref: ../components/schemas/v1organizationsCreateOrganization.yaml + description: Organization details + required: true diff --git a/openapi/paths/api_v1_organizations:external_{external_id}.yaml b/openapi/paths/api_v1_organizations:external_{external_id}.yaml new file mode 100644 index 000000000..48837f1be --- /dev/null +++ b/openapi/paths/api_v1_organizations:external_{external_id}.yaml @@ -0,0 +1,52 @@ +get: + description: >- + Retrieves organization details by external ID, including name, region, + metadata, and settings. Only provide external_id in the path. If the id + query parameter is also supplied, it silently takes precedence over + external_id due to protobuf oneof semantics, which causes the request to + fail with a 400 Bad Request ('ExternalId is required'). + tags: + - Organizations + summary: Get organization details by external Id + operationId: OrganizationService_GetOrganizationByExternalId + parameters: + - schema: + type: string + description: >- + Unique identifier that links an organization to your app's tenant. Use + this with the GetOrganizationByExternalId endpoint. Only one of id or + external_id should be provided per request. + name: external_id + in: path + required: true + - schema: + type: string + description: >- + Unique Scalekit-generated identifier for an organization. Use this with + the GetOrganization endpoint. Do not pass this parameter when calling + GetOrganizationByExternalId — use external_id instead. + name: id + in: query + responses: + '200': + description: >- + Returns the complete organization object with ID, display name, + settings, external ID and metadata + content: + application/json: + schema: + $ref: ../components/schemas/organizationsGetOrganizationResponse.yaml + '400': + description: >- + Invalid request - external ID is empty or the caller's organization + claim does not match + content: + application/json: + schema: {} + '404': + description: >- + Organization not found - no organization exists with the specified + external ID + content: + application/json: + schema: {} diff --git a/openapi/paths/api_v1_organizations_{id}.yaml b/openapi/paths/api_v1_organizations_{id}.yaml new file mode 100644 index 000000000..e8ca3cadf --- /dev/null +++ b/openapi/paths/api_v1_organizations_{id}.yaml @@ -0,0 +1,133 @@ +get: + description: >- + Retrieves organization details by Scalekit ID, including name, region, + metadata, and settings + tags: + - Organizations + summary: Get organization details + operationId: OrganizationService_GetOrganization + parameters: + - schema: + type: string + description: >- + Unique Scalekit-generated identifier for an organization. Use this with + the GetOrganization endpoint. Do not pass this parameter when calling + GetOrganizationByExternalId — use external_id instead. + name: id + in: path + required: true + responses: + '200': + description: >- + Returns the complete organization object with ID, display name, + settings, and metadata + content: + application/json: + schema: + $ref: ../components/schemas/organizationsGetOrganizationResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_organizations_{id}/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_organizations_{id}/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_organizations_{id}/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_organizations_{id}/get.java +delete: + description: >- + Remove an existing organization from the environment using its unique + identifier + tags: + - Organizations + summary: Delete an organization + operationId: OrganizationService_DeleteOrganization + parameters: + - schema: + type: string + description: >- + Unique scalekit-generated identifier that uniquely references an + organization + name: id + in: path + required: true + responses: + '200': + description: Organization successfully deleted and no longer accessible + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_organizations_{id}/delete.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_organizations_{id}/delete.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_organizations_{id}/delete.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_organizations_{id}/delete.java +patch: + description: >- + Updates an organization's display name, external ID, or metadata. Requires a + valid organization identifier. Region code cannot be modified through this + endpoint. + tags: + - Organizations + summary: Update organization details + operationId: OrganizationService_UpdateOrganization + parameters: + - schema: + type: string + description: Unique identifier of the organization to be updated + name: id + in: path + required: true + responses: + '200': + description: >- + Returns the updated organization with all current details reflected in + the response. + content: + application/json: + schema: + $ref: ../components/schemas/organizationsUpdateOrganizationResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_organizations_{id}/patch.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_organizations_{id}/patch.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_organizations_{id}/patch.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_organizations_{id}/patch.java + requestBody: + content: + application/json: + schema: + description: Organization Parameters to be updated + $ref: ../components/schemas/v1organizationsUpdateOrganization.yaml + required: true diff --git a/openapi/paths/api_v1_organizations_{id}_portal_links.yaml b/openapi/paths/api_v1_organizations_{id}_portal_links.yaml new file mode 100644 index 000000000..ee71e4f6b --- /dev/null +++ b/openapi/paths/api_v1_organizations_{id}_portal_links.yaml @@ -0,0 +1,70 @@ +put: + description: >- + Creates a single use Admin Portal URL valid for 1 minute. Once the generated + admin portal URL is accessed or rendered, a temporary session of 6 hours is + created to allow the admin to update SSO/SCIM configuration. + tags: + - Organizations + summary: Generate admin portal link + operationId: OrganizationService_GeneratePortalLink + parameters: + - schema: + type: string + description: Organization ID + name: id + in: path + required: true + - schema: + type: array + items: + enum: + - dir_sync + - sso + type: string + style: form + explode: true + description: >- + Features to enable in the admin portal link. To enable features, append + them as URL parameters: + + + - Single Sign-On: ?features=sso + + - Directory Sync: ?features=dir_sync + + - Both features: ?features=sso&features=dir_sync + + + Example URL: https://scalekit.com/portal/lnk_123?features=sso + + - dir_sync: Enables directory synchronization configuration in the portal + - sso: Enables Single Sign-On (SSO) configuration in the portal + name: features + in: query + responses: + '200': + description: >- + Admin Portal link generated successfully. Returns the portal URL and + expiration timestamp. + content: + application/json: + schema: + $ref: ../components/schemas/organizationsGeneratePortalLinkResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{id}_portal_links/put.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_organizations_{id}_portal_links/put.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_organizations_{id}_portal_links/put.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_organizations_{id}_portal_links/put.java diff --git a/openapi/paths/api_v1_organizations_{id}_settings.yaml b/openapi/paths/api_v1_organizations_{id}_settings.yaml new file mode 100644 index 000000000..4a4383ec8 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{id}_settings.yaml @@ -0,0 +1,73 @@ +patch: + description: >- + Updates configuration settings for an organization. Supports modifying SSO + configuration, directory synchronization settings, and session parameters. + Requires organization ID and the specific settings to update. + tags: + - Organizations + summary: Toggle organization settings + operationId: OrganizationService_UpdateOrganizationSettings + parameters: + - schema: + type: string + description: >- + Unique identifier of the organization to update settings. Must begin + with 'org_' prefix + name: id + in: path + required: true + responses: + '200': + description: >- + Returns the complete organization object with updated settings applied. + Contains all organization details including ID, display name, and the + modified settings. + content: + application/json: + schema: + $ref: ../components/schemas/organizationsGetOrganizationResponse.yaml + '400': + description: >- + Invalid request - occurs when the settings payload contains invalid + values or unsupported configuration + content: + application/json: + schema: {} + '404': + description: Organization not found - the specified organization ID doesn't exist + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_organizations_{id}_settings/patch.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_organizations_{id}_settings/patch.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_organizations_{id}_settings/patch.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_organizations_{id}_settings/patch.java + requestBody: + content: + application/json: + schema: + description: >- + Settings configuration to apply to the organization. Contains + feature toggles for SSO, directory synchronization, and other + organization capabilities + $ref: ../components/schemas/organizationsOrganizationSettings.yaml + examples: + - features: + - enabled: true + name: sso + - enabled: false + name: directory_sync + required: true diff --git a/openapi/paths/api_v1_organizations_{org_id}_roles.yaml b/openapi/paths/api_v1_organizations_{org_id}_roles.yaml new file mode 100644 index 000000000..c2026a2c6 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{org_id}_roles.yaml @@ -0,0 +1,106 @@ +get: + description: >- + Retrieves all environment roles and organization specific roles. Use this + endpoint to view all role definitions, including custom roles and their + configurations. You can optionally include permission details for each role + to understand their capabilities. This is useful for role management, + auditing organization access controls, or understanding the available access + levels within the organization. + tags: + - Roles + summary: List organization roles + operationId: RolesService_ListOrganizationRoles + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: org_id + in: path + required: true + - schema: + type: string + description: >- + Include additional data in the response. Valid values: 'permissions' + (direct permissions only), 'permissions:all' (includes inherited + permissions) + name: include + in: query + responses: + '200': + description: >- + Successfully retrieved list of organization roles. Returns all roles + with their metadata and optionally their permissions. + content: + application/json: + schema: + $ref: ../components/schemas/rolesListOrganizationRolesResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_organizations_{org_id}_roles/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_organizations_{org_id}_roles/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_organizations_{org_id}_roles/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_organizations_{org_id}_roles/get.java +post: + description: >- + Creates a new role within the specified organization with basic + configuration including name, display name, description, and permissions. + Use this endpoint to define custom roles that can be assigned to users + within the organization. You can create hierarchical roles by extending + existing roles and assign specific permissions to control access levels. The + role will be scoped to the organization and can be used for + organization-specific access control. + tags: + - Roles + summary: Create organization role + operationId: RolesService_CreateOrganizationRole + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: org_id + in: path + required: true + responses: + '201': + description: >- + Organization role created successfully. Returns the complete role object + with system-generated ID and timestamps. + content: + application/json: + schema: + $ref: ../components/schemas/rolesCreateOrganizationRoleResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_organizations_{org_id}_roles/post.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_organizations_{org_id}_roles/post.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_organizations_{org_id}_roles/post.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_organizations_{org_id}_roles/post.java + requestBody: + content: + application/json: + schema: + description: Organization role details + $ref: ../components/schemas/v1rolesCreateOrganizationRole.yaml + required: true diff --git a/openapi/paths/api_v1_organizations_{org_id}_roles:set_defaults.yaml b/openapi/paths/api_v1_organizations_{org_id}_roles:set_defaults.yaml new file mode 100644 index 000000000..b19ee3066 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{org_id}_roles:set_defaults.yaml @@ -0,0 +1,56 @@ +patch: + description: >- + Updates the default member role for the specified organization. Use this + endpoint to configure which role is automatically assigned to new users when + they join the organization. The system will validate that the specified role + exists and update the organization settings accordingly. This configuration + affects all new user invitations and memberships within the organization. + tags: + - Roles + summary: Set default organization roles + operationId: RolesService_UpdateDefaultOrganizationRoles + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: org_id + in: path + required: true + responses: + '200': + description: >- + Default organization roles updated successfully. Returns the updated + default member role object with complete role information. + content: + application/json: + schema: + $ref: >- + ../components/schemas/rolesUpdateDefaultOrganizationRolesResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{org_id}_roles:set_defaults/patch.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{org_id}_roles:set_defaults/patch.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{org_id}_roles:set_defaults/patch.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{org_id}_roles:set_defaults/patch.java + requestBody: + content: + application/json: + schema: + $ref: >- + ../components/schemas/RolesServiceUpdateDefaultOrganizationRolesBody.yaml + required: true diff --git a/openapi/paths/api_v1_organizations_{org_id}_roles_{role_name}.yaml b/openapi/paths/api_v1_organizations_{org_id}_roles_{role_name}.yaml new file mode 100644 index 000000000..99cc105a4 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{org_id}_roles_{role_name}.yaml @@ -0,0 +1,187 @@ +get: + description: >- + Retrieves complete information for a specific organization role including + metadata, inheritance details, and optionally permissions. Use this endpoint + to audit role configuration and understand the role's place in the + organization's role hierarchy. You can include permission details to see + what capabilities the role provides. This operation is useful for role + management, user assignment decisions, or understanding organization access + controls. + tags: + - Roles + summary: Get organization role details + operationId: RolesService_GetOrganizationRole + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: org_id + in: path + required: true + - schema: + type: string + description: Unique name of the role + name: role_name + in: path + required: true + - schema: + type: string + description: >- + Include additional data in the response. Valid values: 'permissions' + (direct permissions only), 'permissions:all' (includes inherited + permissions) + name: include + in: query + responses: + '200': + description: >- + Successfully retrieved organization role details. Returns the role + object including metadata and inheritance details. Permissions are + included only when requested via the include parameter. + content: + application/json: + schema: + $ref: ../components/schemas/rolesGetOrganizationRoleResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{org_id}_roles_{role_name}/get.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{org_id}_roles_{role_name}/get.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{org_id}_roles_{role_name}/get.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{org_id}_roles_{role_name}/get.java +put: + description: >- + Modifies an existing organization role's properties including display name, + description, permissions, and inheritance settings. Use this endpoint to + update role metadata, change permission assignments, or modify role + hierarchy within the organization. Only the fields you specify will be + updated, leaving other properties unchanged. When updating permissions, the + new list replaces all existing permissions for the role. + tags: + - Roles + summary: Update organization role + operationId: RolesService_UpdateOrganizationRole + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: org_id + in: path + required: true + - schema: + type: string + description: Unique name of the role + name: role_name + in: path + required: true + responses: + '200': + description: >- + Organization role updated successfully. Returns the modified role object + with updated timestamps. + content: + application/json: + schema: + $ref: ../components/schemas/rolesUpdateOrganizationRoleResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{org_id}_roles_{role_name}/put.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{org_id}_roles_{role_name}/put.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{org_id}_roles_{role_name}/put.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{org_id}_roles_{role_name}/put.java + requestBody: + content: + application/json: + schema: + description: Organization role details + $ref: ../components/schemas/v1rolesUpdateRole.yaml + required: true +delete: + description: >- + Permanently removes a role from the organization and optionally reassigns + users who had that role to a different role. Use this endpoint when you need + to clean up unused roles or restructure your organization's access control + system. If users are assigned to the role being deleted, you can provide a + reassign_role_name to move those users to a different role before deletion. + This action cannot be undone, so ensure no critical users depend on the role + before deletion. + tags: + - Roles + summary: Delete organization role + operationId: RolesService_DeleteOrganizationRole + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: org_id + in: path + required: true + - schema: + type: string + description: Unique name of the role + name: role_name + in: path + required: true + - schema: + type: string + description: Role name to reassign users to when deleting this role + name: reassign_role_name + in: query + responses: + '200': + description: >- + Organization role successfully deleted and users reassigned if + specified. No content returned. + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{org_id}_roles_{role_name}/delete.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{org_id}_roles_{role_name}/delete.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{org_id}_roles_{role_name}/delete.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{org_id}_roles_{role_name}/delete.java diff --git a/openapi/paths/api_v1_organizations_{organization_id}_clients.yaml b/openapi/paths/api_v1_organizations_{organization_id}_clients.yaml new file mode 100644 index 000000000..bd39ce806 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_clients.yaml @@ -0,0 +1,93 @@ +get: + description: >- + Retrieves a paginated list of API clients for a specific organization. + Returns client details including metadata, scopes, and secret information + (without exposing actual secret values). + tags: + - API Auth + summary: List organization API clients + operationId: ClientService_ListOrganizationClients + parameters: + - schema: + type: string + description: >- + Unique identifier of the organization whose clients to list. Must start + with 'org_' prefix. + name: organization_id + in: path + required: true + - schema: + type: integer + format: int64 + description: >- + Maximum number of clients to return per page + + + Maximum number of API clients to return per page. Must be between 10 and + 100 + name: page_size + in: query + - schema: + type: string + description: >- + Pagination token from the previous response + + + Pagination token from the previous response. Use to retrieve the next + page of organization clients + name: page_token + in: query + responses: + '200': + description: >- + List of organization API clients returned successfully. Each client + includes its configuration details and metadata. + content: + application/json: + schema: + $ref: ../components/schemas/clientsListOrganizationClientsResponse.yaml + x-codeSamples: + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_clients/get.py +post: + description: >- + Creates a new API client for an organization. Returns the client details and + a plain secret (available only once). + tags: + - API Auth + summary: Create organization API client + operationId: ClientService_CreateOrganizationClient + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + responses: + '201': + description: >- + API client created successfully. Returns the client ID and plain secret + (only available at creation time). The client can be configured with + scopes, audience values, and custom claims for fine-grained access + control. + content: + application/json: + schema: + $ref: ../components/schemas/clientsCreateOrganizationClientResponse.yaml + x-codeSamples: + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_clients/post.py + requestBody: + content: + application/json: + schema: + description: Details of the client to be created + $ref: ../components/schemas/clientsOrganizationClient.yaml + required: true diff --git a/openapi/paths/api_v1_organizations_{organization_id}_clients_{client_id}.yaml b/openapi/paths/api_v1_organizations_{organization_id}_clients_{client_id}.yaml new file mode 100644 index 000000000..5ba98f30a --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_clients_{client_id}.yaml @@ -0,0 +1,118 @@ +get: + description: Retrieves details of a specific API client in an organization. + tags: + - API Auth + summary: Get organization API client + operationId: ClientService_GetOrganizationClient + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the API client + name: client_id + in: path + required: true + responses: + '200': + description: >- + Returns the complete API client configuration, including all current + settings and a list of active secrets. Note that secret values are not + included in the response for security reasons. + content: + application/json: + schema: + $ref: ../components/schemas/clientsGetOrganizationClientResponse.yaml + x-codeSamples: + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}/get.py +delete: + description: >- + Permanently deletes an API client from an organization. This operation + cannot be undone and will revoke all access for the client. All associated + secrets will also be invalidated. Use this endpoint to remove unused or + compromised clients. + tags: + - API Auth + summary: Delete organization API client + operationId: ClientService_DeleteOrganizationClient + parameters: + - schema: + type: string + description: >- + Unique identifier of the organization that owns the client. Must start + with 'org_' prefix. + name: organization_id + in: path + required: true + - schema: + type: string + description: >- + Unique identifier of the API client to permanently delete. Must start + with 'm2morg_' prefix. + name: client_id + in: path + required: true + responses: + '200': + description: Organization API client successfully deleted and no longer accessible + content: + application/json: + schema: {} + x-codeSamples: + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}/delete.py +patch: + description: >- + Updates an existing organization API client. Only specified fields are + modified. + tags: + - API Auth + summary: Update organization API client + operationId: ClientService_UpdateOrganizationClient + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the client + name: client_id + in: path + required: true + responses: + '200': + description: >- + Returns the updated organization API client with all current details + reflected in the response, including modified scopes, audience values, + and custom claims. + content: + application/json: + schema: + $ref: ../components/schemas/clientsUpdateOrganizationClientResponse.yaml + x-codeSamples: + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}/patch.py + requestBody: + content: + application/json: + schema: + description: Updated details for the client + $ref: ../components/schemas/clientsOrganizationClient.yaml + required: true diff --git a/openapi/paths/api_v1_organizations_{organization_id}_clients_{client_id}_secrets.yaml b/openapi/paths/api_v1_organizations_{organization_id}_clients_{client_id}_secrets.yaml new file mode 100644 index 000000000..692b342e8 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_clients_{client_id}_secrets.yaml @@ -0,0 +1,38 @@ +post: + description: >- + Creates a new secret for an organization API client. Returns the plain + secret (available only once). + tags: + - API Auth + summary: Create organization API client secret + operationId: ClientService_CreateOrganizationClientSecret + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the API client + name: client_id + in: path + required: true + responses: + '201': + description: >- + Client secret created successfully. Returns the new secret ID and the + plain secret value (only available at creation time). The secret can be + used immediately for authentication. + content: + application/json: + schema: + $ref: >- + ../components/schemas/clientsCreateOrganizationClientSecretResponse.yaml + x-codeSamples: + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}_secrets/post.py diff --git a/openapi/paths/api_v1_organizations_{organization_id}_clients_{client_id}_secrets_{secret_id}.yaml b/openapi/paths/api_v1_organizations_{organization_id}_clients_{client_id}_secrets_{secret_id}.yaml new file mode 100644 index 000000000..433d2e655 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_clients_{client_id}_secrets_{secret_id}.yaml @@ -0,0 +1,39 @@ +delete: + description: >- + Permanently deletes a secret from an organization API client. This operation + cannot be undone. + tags: + - API Auth + summary: Delete organization API client secret + operationId: ClientService_DeleteOrganizationClientSecret + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the API client + name: client_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the client secret + name: secret_id + in: path + required: true + responses: + '200': + description: Client secret successfully deleted and no longer accessible + content: + application/json: + schema: {} + x-codeSamples: + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_clients_{client_id}_secrets_{secret_id}/delete.py diff --git a/openapi/paths/api_v1_organizations_{organization_id}_connections_{id}.yaml b/openapi/paths/api_v1_organizations_{organization_id}_connections_{id}.yaml new file mode 100644 index 000000000..621ea03cd --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_connections_{id}.yaml @@ -0,0 +1,104 @@ +get: + description: >- + Retrieves the complete configuration and status details for a specific + connection by its ID within an organization. Returns all connection + properties including provider settings, protocols, and current status. + tags: + - Connections + summary: Get connection details + operationId: ConnectionService_GetConnection + parameters: + - schema: + type: string + description: >- + Organization identifier (required). Specifies which organization owns + the connection you want to retrieve. + name: organization_id + in: path + required: true + - schema: + type: string + description: >- + Connection identifier (required). Specifies which specific connection to + retrieve from the organization. + name: id + in: path + required: true + responses: + '200': + description: Successfully retrieved connection details for the specified organization + content: + application/json: + schema: + $ref: ../components/schemas/connectionsGetConnectionResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}/get.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_connections_{id}/get.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_connections_{id}/get.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_connections_{id}/get.java +delete: + description: >- + Deletes an SSO connection from the specified organization by connection ID. + Use this endpoint when an identity provider integration is no longer needed + for the organization. Returns an empty response after the SSO connection is + deleted successfully. + tags: + - Connections + summary: Delete SSO connection + operationId: ConnectionService_DeleteConnection + parameters: + - schema: + type: string + description: Organization ID for the Connection. + name: organization_id + in: path + required: true + - schema: + type: string + description: Connection ID. Unique ID for the connection + name: id + in: path + required: true + responses: + '200': + description: SSO connection deleted successfully + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}/delete.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_connections_{id}/delete.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_connections_{id}/delete.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_connections_{id}/delete.java diff --git a/openapi/paths/api_v1_organizations_{organization_id}_connections_{id}:disable.yaml b/openapi/paths/api_v1_organizations_{organization_id}_connections_{id}:disable.yaml new file mode 100644 index 000000000..f51772452 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_connections_{id}:disable.yaml @@ -0,0 +1,51 @@ +patch: + description: >- + Deactivate an existing connection for the specified organization. When + disabled, users cannot authenticate using this connection. This endpoint + changes the connection state from enabled to disabled without modifying + other configuration settings + tags: + - Connections + summary: Disable SSO connection + operationId: ConnectionService_DisableConnection + parameters: + - schema: + type: string + description: Unique identifier of the organization associated with the connection + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier for the connection to be toggled + name: id + in: path + required: true + responses: + '200': + description: Connection disabled successfully + content: + application/json: + schema: + $ref: ../components/schemas/connectionsToggleConnectionResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_connections_{id}:disable/patch.java diff --git a/openapi/paths/api_v1_organizations_{organization_id}_connections_{id}:enable.yaml b/openapi/paths/api_v1_organizations_{organization_id}_connections_{id}:enable.yaml new file mode 100644 index 000000000..77cd9bc18 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_connections_{id}:enable.yaml @@ -0,0 +1,51 @@ +patch: + description: >- + Activate an existing connection for the specified organization. When + enabled, users can authenticate using this connection. This endpoint changes + the connection state from disabled to enabled without modifying other + configuration settings + tags: + - Connections + summary: Enable SSO connection + operationId: ConnectionService_EnableConnection + parameters: + - schema: + type: string + description: Unique identifier of the organization associated with the connection + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier for the connection to be toggled + name: id + in: path + required: true + responses: + '200': + description: Connection enabled successfully + content: + application/json: + schema: + $ref: ../components/schemas/connectionsToggleConnectionResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_connections_{id}:enable/patch.java diff --git a/openapi/paths/api_v1_organizations_{organization_id}_directories.yaml b/openapi/paths/api_v1_organizations_{organization_id}_directories.yaml new file mode 100644 index 000000000..44c88cd06 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_directories.yaml @@ -0,0 +1,40 @@ +get: + tags: + - Directory + summary: List organization directories + operationId: DirectoryService_ListDirectories + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + responses: + '200': + description: Successfully retrieved the list of directories for the organization + content: + application/json: + schema: + $ref: ../components/schemas/directoriesListDirectoriesResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_directories/get.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_directories/get.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_directories/get.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_directories/get.java diff --git a/openapi/paths/api_v1_organizations_{organization_id}_directories_{directory_id}_groups.yaml b/openapi/paths/api_v1_organizations_{organization_id}_directories_{directory_id}_groups.yaml new file mode 100644 index 000000000..eeea3df12 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_directories_{directory_id}_groups.yaml @@ -0,0 +1,84 @@ +get: + description: >- + Retrieves all groups from a specified directory. Use this endpoint to view + group structures from your connected identity provider. + tags: + - Directory + summary: List directory groups + operationId: DirectoryService_ListDirectoryGroups + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the directory + name: directory_id + in: path + required: true + - schema: + type: integer + format: int64 + description: >- + Number of groups to return per page. Maximum value is 30. If not + specified, defaults to 10 + name: page_size + in: query + - schema: + type: string + description: >- + Token for pagination. Use the value returned in the 'next_page_token' + field of the previous response + name: page_token + in: query + - schema: + type: string + format: date-time + description: Filter groups updated after this timestamp. Use ISO 8601 format + name: updated_after + in: query + - schema: + type: boolean + description: >- + If true, includes full group details. If false or not specified, returns + basic information only + name: include_detail + in: query + - schema: + type: boolean + description: >- + If true, returns group and its details from external provider (default: + false) + name: include_external_groups + in: query + responses: + '200': + description: Successfully retrieved the list of groups from the specified directory + content: + application/json: + schema: + $ref: ../components/schemas/directoriesListDirectoryGroupsResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_directories_{directory_id}_groups/get.java diff --git a/openapi/paths/api_v1_organizations_{organization_id}_directories_{directory_id}_users.yaml b/openapi/paths/api_v1_organizations_{organization_id}_directories_{directory_id}_users.yaml new file mode 100644 index 000000000..f1de05230 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_directories_{directory_id}_users.yaml @@ -0,0 +1,86 @@ +get: + description: >- + Retrieves a list of all users within a specified directory for an + organization. This endpoint allows you to view user accounts associated with + your connected Directory Providers. + tags: + - Directory + summary: List directory users + operationId: DirectoryService_ListDirectoryUsers + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the directory within the organization + name: directory_id + in: path + required: true + - schema: + type: integer + format: int64 + description: >- + Number of users to return per page. Maximum value is 30. If not + specified, defaults to 10 + name: page_size + in: query + - schema: + type: string + description: >- + Token for pagination. Use the value returned in the 'next_page_token' + field of the previous response to retrieve the next page of results + name: page_token + in: query + - schema: + type: boolean + description: >- + If set to true, the response will include the full user payload with all + available details. If false or not specified, only essential user + information will be returned + name: include_detail + in: query + - schema: + type: string + description: Filter users by their membership in a specific directory group + name: directory_group_id + in: query + - schema: + type: string + format: date-time + description: >- + Filter users that were updated after the specified timestamp. Use ISO + 8601 format + name: updated_after + in: query + responses: + '200': + description: Successfully retrieved the list of users from the specified directory + content: + application/json: + schema: + $ref: ../components/schemas/directoriesListDirectoryUsersResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_directories_{directory_id}_users/get.java diff --git a/openapi/paths/api_v1_organizations_{organization_id}_directories_{id}.yaml b/openapi/paths/api_v1_organizations_{organization_id}_directories_{id}.yaml new file mode 100644 index 000000000..cda14dd2c --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_directories_{id}.yaml @@ -0,0 +1,49 @@ +get: + description: >- + Retrieves detailed information about a specific directory within an + organization + tags: + - Directory + summary: Get directory details + operationId: DirectoryService_GetDirectory + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the directory + name: id + in: path + required: true + responses: + '200': + description: Successfully retrieved directory details + content: + application/json: + schema: + $ref: ../components/schemas/directoriesGetDirectoryResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_directories_{id}/get.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_directories_{id}/get.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_directories_{id}/get.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_directories_{id}/get.java diff --git a/openapi/paths/api_v1_organizations_{organization_id}_directories_{id}:disable.yaml b/openapi/paths/api_v1_organizations_{organization_id}_directories_{id}:disable.yaml new file mode 100644 index 000000000..144c38d47 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_directories_{id}:disable.yaml @@ -0,0 +1,54 @@ +patch: + description: >- + Stops synchronization of users and groups from a specified directory within + an organization. This operation prevents further updates from the connected + Directory provider + tags: + - Directory + summary: Disable a directory + operationId: DirectoryService_DisableDirectory + parameters: + - schema: + type: string + description: >- + A unique identifier for the organization. The value must begin with + 'org_' and be between 1 and 32 characters long + name: organization_id + in: path + required: true + - schema: + type: string + description: >- + A unique identifier for a directory within the organization. The value + must begin with 'dir_' and be between 1 and 32 characters long + name: id + in: path + required: true + responses: + '200': + description: Successfully disabled the directory + content: + application/json: + schema: + $ref: ../components/schemas/directoriesToggleDirectoryResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_directories_{id}:disable/patch.java diff --git a/openapi/paths/api_v1_organizations_{organization_id}_directories_{id}:enable.yaml b/openapi/paths/api_v1_organizations_{organization_id}_directories_{id}:enable.yaml new file mode 100644 index 000000000..3aa7ed5e5 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_directories_{id}:enable.yaml @@ -0,0 +1,53 @@ +patch: + description: >- + Activates a directory within an organization, allowing it to synchronize + users and groups with the connected Directory provider + tags: + - Directory + summary: Enable a directory + operationId: DirectoryService_EnableDirectory + parameters: + - schema: + type: string + description: >- + A unique identifier for the organization. The value must begin with + 'org_' and be between 1 and 32 characters long + name: organization_id + in: path + required: true + - schema: + type: string + description: >- + A unique identifier for a directory within the organization. The value + must begin with 'dir_' and be between 1 and 32 characters long + name: id + in: path + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: ../components/schemas/directoriesToggleDirectoryResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_directories_{id}:enable/patch.java diff --git a/openapi/paths/api_v1_organizations_{organization_id}_domains.yaml b/openapi/paths/api_v1_organizations_{organization_id}_domains.yaml new file mode 100644 index 000000000..556730def --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_domains.yaml @@ -0,0 +1,166 @@ +get: + description: >+ + Retrieves a paginated list of all domains configured for the specified + organization. + + + Domain types: + + - ALLOWED_EMAIL_DOMAIN: Trusted domains used to suggest the organization in + the organization switcher during sign-in/sign-up (auth-method agnostic). + + - ORGANIZATION_DOMAIN: SSO discovery domains used to route users to the + correct SSO provider and enforce SSO. + + tags: + - Domains + summary: List Domains + operationId: DomainService_ListDomains + parameters: + - schema: + type: string + description: >- + Scalekit-generated unique identifier for the organization. Use either + this or external_id to identify the organization. + name: organization_id + in: path + required: true + - schema: + type: string + description: >- + Optional comma-separated list of additional fields to include in the + response (e.g., 'verification_details'). + name: include + in: query + - schema: + type: integer + format: int32 + description: >- + Maximum number of domains to return per page. Default is 30, maximum is + 100. + name: page_size + in: query + - schema: + type: integer + format: int32 + description: Page number to retrieve (0-based). Use 0 for the first page. + name: page_number + in: query + - schema: + type: string + enum: + - ALLOWED_EMAIL_DOMAIN + - ORGANIZATION_DOMAIN + description: > + The domain type. + + - ALLOWED_EMAIL_DOMAIN: trusted domain used to suggest the organization + in the organization switcher during sign-in/sign-up. + + - ORGANIZATION_DOMAIN: SSO discovery domain used to route users to the + correct SSO provider and enforce SSO. + name: domain_type + in: query + responses: + '200': + description: Successfully retrieved the list of domains. + content: + application/json: + schema: + $ref: ../components/schemas/domainsListDomainResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_domains/get.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_domains/get.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_domains/get.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_domains/get.java +post: + description: >+ + Creates and associates a domain with an organization. + + + Use one of the following domain types: + + - ALLOWED_EMAIL_DOMAIN: Adds a trusted email domain for organization + suggestions in the organization switcher during sign-in/sign-up (auth-method + agnostic). + + - ORGANIZATION_DOMAIN: Enables SSO domain discovery. If a user signs in with + a matching email domain, Scalekit redirects them to the organization’s SSO + provider and enforces SSO. + + + The domain must be a valid business domain that you control. + Public/disposable domains (e.g., gmail.com) are blocked for security. + + tags: + - Domains + summary: Create Domain + operationId: DomainService_CreateDomain + parameters: + - schema: + type: string + description: >- + Scalekit-generated unique identifier for the organization. Use either + this or external_id to identify the organization. + name: organization_id + in: path + required: true + responses: + '200': + description: Successfully created the domain. + content: + application/json: + schema: + $ref: ../components/schemas/domainsCreateDomainResponse.yaml + '400': + description: >- + Invalid request — common causes invalid domain format, public or + disposable domain, or domain already exists. + content: + application/json: + schema: + $ref: ../components/schemas/errdetailsErrorInfo.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_domains/post.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_domains/post.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_domains/post.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_domains/post.java + requestBody: + content: + application/json: + schema: + description: Domain configuration including the domain name and type. + $ref: ../components/schemas/v1domainsCreateDomain.yaml + required: true diff --git a/openapi/paths/api_v1_organizations_{organization_id}_domains_{id}.yaml b/openapi/paths/api_v1_organizations_{organization_id}_domains_{id}.yaml new file mode 100644 index 000000000..63bc56952 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_domains_{id}.yaml @@ -0,0 +1,111 @@ +get: + description: >+ + Retrieves complete details for a domain including domain type, timestamps, + and configuration information. + + tags: + - Domains + summary: Get Domain + operationId: DomainService_GetDomain + parameters: + - schema: + type: string + description: >- + Scalekit-generated unique identifier for the organization. Use either + this or external_id to identify the organization. + name: organization_id + in: path + required: true + - schema: + type: string + description: Scalekit-generated unique identifier of the domain to retrieve. + name: id + in: path + required: true + responses: + '200': + description: Successfully retrieved the domain details. + content: + application/json: + schema: + $ref: ../components/schemas/domainsGetDomainResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_domains_{id}/get.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_domains_{id}/get.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_domains_{id}/get.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_domains_{id}/get.java +delete: + description: >+ + Permanently removes a domain record from an organization. + + + - Deleting an ORGANIZATION_DOMAIN disables SSO routing/enforcement for that + domain. + + - Deleting an ALLOWED_EMAIL_DOMAIN stops organization suggestions for users + with that email domain. + + tags: + - Domains + summary: Delete Domain + operationId: DomainService_DeleteDomain + parameters: + - schema: + type: string + description: >- + Scalekit-generated unique identifier for the organization. Use either + this or external_id to identify the organization. + name: organization_id + in: path + required: true + - schema: + type: string + description: >- + Scalekit-generated unique identifier of the domain to be permanently + deleted. + name: id + in: path + required: true + responses: + '200': + description: Domain successfully deleted. + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_domains_{id}/delete.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_domains_{id}/delete.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_domains_{id}/delete.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_domains_{id}/delete.java diff --git a/openapi/paths/api_v1_organizations_{organization_id}_session-policy.yaml b/openapi/paths/api_v1_organizations_{organization_id}_session-policy.yaml new file mode 100644 index 000000000..12e8d613b --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_session-policy.yaml @@ -0,0 +1,71 @@ +get: + description: >- + Retrieves the session policy for an organization. Returns + session_policy='APPLICATION' if the organization inherits the + application-level defaults, or session_policy='CUSTOM' with the configured + values if a custom policy is active. + tags: + - Organizations + summary: Get organization session policy + operationId: OrganizationService_GetOrganizationSessionPolicy + parameters: + - schema: + type: string + description: >- + The unique identifier of the organization whose session policy is being + requested. + name: organization_id + in: path + required: true + responses: + '200': + description: Session policy retrieved successfully. + content: + application/json: + schema: + $ref: >- + ../components/schemas/organizationsGetOrganizationSessionPolicyResponse.yaml + '404': + description: Organization not found. + content: + application/json: + schema: {} +patch: + description: >- + Sets a custom session policy for an organization or reverts to + application-level settings. Send session_policy='APPLICATION' to revert to + application defaults. Send session_policy='CUSTOM' with timeout values to + activate a custom policy. + tags: + - Organizations + summary: Update organization session policy + operationId: OrganizationService_UpdateOrganizationSessionPolicy + parameters: + - schema: + type: string + description: >- + The unique identifier of the organization whose session policy is being + updated. + name: organization_id + in: path + required: true + responses: + '200': + description: Session policy updated successfully. + content: + application/json: + schema: + $ref: >- + ../components/schemas/organizationsUpdateOrganizationSessionPolicyResponse.yaml + '404': + description: Organization not found. + content: + application/json: + schema: {} + requestBody: + content: + application/json: + schema: + $ref: >- + ../components/schemas/OrganizationServiceUpdateOrganizationSessionPolicyBody.yaml + required: true diff --git a/openapi/paths/api_v1_organizations_{organization_id}_settings_usermanagement.yaml b/openapi/paths/api_v1_organizations_{organization_id}_settings_usermanagement.yaml new file mode 100644 index 000000000..22bef1ad0 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_settings_usermanagement.yaml @@ -0,0 +1,28 @@ +patch: + description: Upsert user management settings for an organization + tags: + - Organizations + summary: Upsert organization user setting + operationId: OrganizationService_UpsertUserManagementSettings + parameters: + - schema: + type: string + description: ID of the organization. + name: organization_id + in: path + required: true + responses: + '200': + description: Returns the updated organization setting. + content: + application/json: + schema: + $ref: >- + ../components/schemas/organizationsUpsertUserManagementSettingsResponse.yaml + requestBody: + content: + application/json: + schema: + $ref: >- + ../components/schemas/OrganizationServiceUpsertUserManagementSettingsBody.yaml + required: true diff --git a/openapi/paths/api_v1_organizations_{organization_id}_users.yaml b/openapi/paths/api_v1_organizations_{organization_id}_users.yaml new file mode 100644 index 000000000..b3e174350 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_users.yaml @@ -0,0 +1,120 @@ +get: + description: >- + Retrieves a paginated list of all users who are members of the specified + organization. Use this endpoint to view all users with access to a + particular organization, including their roles, metadata, and membership + details. Supports pagination for large user lists. + tags: + - Users + summary: List organization users + operationId: UserService_ListOrganizationUsers + parameters: + - schema: + type: string + description: >- + Unique identifier of the organization for which to list users. Must + start with 'org_' and be 1-32 characters long. + name: organization_id + in: path + required: true + - schema: + type: integer + format: int64 + description: >- + Maximum number of users to return in a single response. Valid range: + 1-100. Server may return fewer users than specified. + name: page_size + in: query + - schema: + type: string + description: >- + Pagination token from a previous ListUserResponse. Used to retrieve the + next page of results. Leave empty for the first request. + name: page_token + in: query + responses: + '200': + description: Successfully retrieved the list of users in the organization + content: + application/json: + schema: + $ref: ../components/schemas/usersListOrganizationUsersResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_users/get.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_users/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_organizations_{organization_id}_users/get.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_users/get.java +post: + description: >- + Creates a new user account and immediately adds them to the specified + organization. Use this endpoint when you want to create a user and grant + them access to an organization in a single operation. You can provide user + profile information, assign roles, and configure membership metadata. The + user receives an activation email unless this feature is disabled in the + organization settings. + tags: + - Users + summary: Create new user in organization + operationId: UserService_CreateUserAndMembership + parameters: + - schema: + type: string + name: organization_id + in: path + required: true + - schema: + type: boolean + description: If true, sends an activation email to the user. Defaults to true. + name: send_invitation_email + in: query + responses: + '201': + description: >- + User created successfully. Returns the created user object, including + system-generated identifiers and timestamps + content: + application/json: + schema: + $ref: ../components/schemas/usersCreateUserAndMembershipResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_users/post.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_users/post.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_users/post.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_users/post.java + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/usersCreateUser.yaml + required: true diff --git a/openapi/paths/api_v1_organizations_{organization_id}_users:search.yaml b/openapi/paths/api_v1_organizations_{organization_id}_users:search.yaml new file mode 100644 index 000000000..1bea167fa --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_users:search.yaml @@ -0,0 +1,69 @@ +get: + description: >- + Searches for users within a specific organization by email address, user ID, + or external ID. The query must be at least 3 characters and is + case-insensitive. Scopes results strictly to the given organization. Returns + a paginated list of matching users with up to 30 results per page. Use the + next_page_token from the response to retrieve subsequent pages. + tags: + - Users + summary: Search organization users + operationId: UserService_SearchOrganizationUsers + parameters: + - schema: + type: string + description: >- + Unique identifier of the organization to search within. Must start with + 'org_' and be 1-32 characters long. + name: organization_id + in: path + required: true + - schema: + type: string + minLength: 3 + maxLength: 100 + description: >- + Search term to match against user email, IDs, or external IDs. Must be + at least 3 characters. Case insensitive. + name: query + in: query + required: true + - schema: + type: integer + format: int64 + minimum: 1 + maximum: 30 + description: >- + Maximum number of users to return per page. Value must be between 1 and + 30. + name: page_size + in: query + - schema: + type: string + description: >- + Token from a previous response for pagination. Provide this to retrieve + the next page of results. + name: page_token + in: query + responses: + '200': + description: >- + Matching users within the organization returned; includes pagination + cursors for navigating large result sets. + content: + application/json: + schema: + $ref: ../components/schemas/usersSearchOrganizationUsersResponse.yaml + '400': + description: >- + Bad Request - query must be at least 3 characters and no more than 100 + characters, and organization_id must be a valid org_ prefixed + identifier. + content: + application/json: + schema: {} + '404': + description: Not Found - organization not found. + content: + application/json: + schema: {} diff --git a/openapi/paths/api_v1_organizations_{organization_id}_users_{user_id}_permissions.yaml b/openapi/paths/api_v1_organizations_{organization_id}_users_{user_id}_permissions.yaml new file mode 100644 index 000000000..03c5a7667 --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_users_{user_id}_permissions.yaml @@ -0,0 +1,50 @@ +get: + description: >- + Retrieves all permissions a user has access to within a specific + organization. This includes permissions from direct role assignments and + inherited permissions from role hierarchy. + tags: + - Users + summary: List user permissions + operationId: UserService_ListUserPermissions + parameters: + - schema: + type: string + description: Unique identifier for the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier for the user + name: user_id + in: path + required: true + responses: + '200': + description: Successfully retrieved the list of permissions for the user + content: + application/json: + schema: + $ref: ../components/schemas/usersListUserPermissionsResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_users_{user_id}_permissions/get.java diff --git a/openapi/paths/api_v1_organizations_{organization_id}_users_{user_id}_roles.yaml b/openapi/paths/api_v1_organizations_{organization_id}_users_{user_id}_roles.yaml new file mode 100644 index 000000000..ca1fd5dcf --- /dev/null +++ b/openapi/paths/api_v1_organizations_{organization_id}_users_{user_id}_roles.yaml @@ -0,0 +1,50 @@ +get: + description: >- + Retrieves all roles assigned to a user within a specific organization. This + includes both direct role assignments and inherited roles from role + hierarchy. + tags: + - Users + summary: List user roles + operationId: UserService_ListUserRoles + parameters: + - schema: + type: string + description: Unique identifier for the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier for the user + name: user_id + in: path + required: true + responses: + '200': + description: Successfully retrieved the list of roles assigned to the user + content: + application/json: + schema: + $ref: ../components/schemas/usersListUserRolesResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_organizations_{organization_id}_users_{user_id}_roles/get.java diff --git a/openapi/paths/api_v1_passwordless_email_resend.yaml b/openapi/paths/api_v1_passwordless_email_resend.yaml new file mode 100644 index 000000000..cb0478acd --- /dev/null +++ b/openapi/paths/api_v1_passwordless_email_resend.yaml @@ -0,0 +1,40 @@ +post: + description: >- + Resend a verification email if the user didn't receive it or if the previous + code/link has expired + tags: + - Magic link & OTP + summary: Resend passwordless email + operationId: PasswordlessService_ResendPasswordlessEmail + responses: + '200': + description: >- + Successfully resent the passwordless authentication email. Returns + updated authentication request details with new expiration time. + content: + application/json: + schema: + $ref: ../components/schemas/passwordlessSendPasswordlessResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_passwordless_email_resend/post.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_passwordless_email_resend/post.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_passwordless_email_resend/post.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_passwordless_email_resend/post.java + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/passwordlessResendPasswordlessRequest.yaml + required: true diff --git a/openapi/paths/api_v1_passwordless_email_send.yaml b/openapi/paths/api_v1_passwordless_email_send.yaml new file mode 100644 index 000000000..96b53029c --- /dev/null +++ b/openapi/paths/api_v1_passwordless_email_send.yaml @@ -0,0 +1,41 @@ +post: + description: >- + Send a verification email containing either a verification code (OTP), magic + link, or both to a user's email address + tags: + - Magic link & OTP + summary: Send passwordless email + operationId: PasswordlessService_SendPasswordlessEmail + responses: + '200': + description: >- + Successfully sent passwordless authentication email. Returns the + authentication request details including expiration time and auth + request ID + content: + application/json: + schema: + $ref: ../components/schemas/passwordlessSendPasswordlessResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_passwordless_email_send/post.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_passwordless_email_send/post.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_passwordless_email_send/post.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_passwordless_email_send/post.java + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/passwordlessSendPasswordlessRequest.yaml + required: true diff --git a/openapi/paths/api_v1_passwordless_email_verify.yaml b/openapi/paths/api_v1_passwordless_email_verify.yaml new file mode 100644 index 000000000..f52cc646d --- /dev/null +++ b/openapi/paths/api_v1_passwordless_email_verify.yaml @@ -0,0 +1,40 @@ +post: + description: >- + Verify a user's identity using either a verification code or magic link + token + tags: + - Magic link & OTP + summary: Verify passwordless email + operationId: PasswordlessService_VerifyPasswordlessEmail + responses: + '200': + description: >- + Successfully verified the passwordless authentication. Returns user + email + content: + application/json: + schema: + $ref: ../components/schemas/passwordlessVerifyPasswordLessResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_passwordless_email_verify/post.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_passwordless_email_verify/post.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_passwordless_email_verify/post.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_passwordless_email_verify/post.java + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/passwordlessVerifyPasswordLessRequest.yaml + required: true diff --git a/openapi/paths/api_v1_permissions.yaml b/openapi/paths/api_v1_permissions.yaml new file mode 100644 index 000000000..caa2bead6 --- /dev/null +++ b/openapi/paths/api_v1_permissions.yaml @@ -0,0 +1,111 @@ +get: + description: >- + Retrieves a comprehensive, paginated list of all permissions available + within the environment. Use this endpoint to view all permission definitions + for auditing, role management, or understanding the complete set of + available access controls. The response includes pagination tokens to + navigate through large sets of permissions efficiently. Each permission + object contains the permission name, description, creation time, and last + update time. This operation is useful for building permission selection + interfaces, auditing permission usage, or understanding the scope of + available access controls in your RBAC system. + tags: + - Permissions + summary: List all permissions + operationId: RolesService_ListPermissions + parameters: + - schema: + type: string + description: Page token to retrieve next page of results + name: page_token + in: query + - schema: + type: integer + format: int64 + description: Number of permissions to return per page (max 100) + name: page_size + in: query + - schema: + type: string + enum: + - SCALEKIT + - ENVIRONMENT + description: >- + Filter permissions by type: ALL, SCALEKIT, or ENVIRONMENT, where + SCALEKIT are predefined Scalekit permissions and ENVIRONMENT are custom + permissions created in the environment, default is ALL + name: type + in: query + responses: + '200': + description: >- + Successfully retrieved the list of permissions. Returns a paginated list + of permission objects with metadata and pagination tokens for + navigation. + content: + application/json: + schema: + $ref: ../components/schemas/rolesListPermissionsResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_permissions/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_permissions/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_permissions/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_permissions/get.java +post: + description: >- + Creates a new permission that represents a specific action users can perform + within the environment. Use this endpoint to define granular access controls + for your RBAC system. You can provide a unique permission name following the + format 'action:resource' (for example, 'read:documents', 'write:users') and + an optional description explaining the permission's purpose. The permission + name must be unique across the environment and follows alphanumeric naming + conventions with colons and underscores. Returns the created permission + object including system-generated ID and timestamps. + tags: + - Permissions + summary: Create new permission + operationId: RolesService_CreatePermission + responses: + '201': + description: >- + Permission created successfully. Returns the complete permission object + with system-generated ID, name, description, and timestamps. + content: + application/json: + schema: + $ref: ../components/schemas/rolesCreatePermissionResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_permissions/post.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_permissions/post.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_permissions/post.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_permissions/post.java + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/v1rolesCreatePermission.yaml + required: true diff --git a/openapi/paths/api_v1_permissions_{permission_name}.yaml b/openapi/paths/api_v1_permissions_{permission_name}.yaml new file mode 100644 index 000000000..1d49ff581 --- /dev/null +++ b/openapi/paths/api_v1_permissions_{permission_name}.yaml @@ -0,0 +1,148 @@ +get: + description: >- + Retrieves complete information for a specific permission by its unique name + identifier. Use this endpoint to view permission details including + description, creation time, and last update time. Provide the permission + name in the path parameter following the format 'action:resource' (for + example, 'read:documents'). This operation is useful for auditing permission + definitions, understanding permission purposes, or verifying permission + existence before assignment. Returns the complete permission object with all + metadata and system-generated timestamps. + tags: + - Permissions + summary: Retrieve permission details + operationId: RolesService_GetPermission + parameters: + - schema: + type: string + description: Name of the permission + name: permission_name + in: path + required: true + responses: + '200': + description: >- + Successfully retrieved permission details. Returns the complete + permission object including name, description, creation time, and update + time. + content: + application/json: + schema: + $ref: ../components/schemas/rolesGetPermissionResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_permissions_{permission_name}/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_permissions_{permission_name}/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_permissions_{permission_name}/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_permissions_{permission_name}/get.java +put: + description: >- + Modifies an existing permission's attributes including description and + metadata. Use this endpoint to update permission descriptions or clarify + permission purposes after creation. The permission is identified by its + unique name in the path parameter, and only the fields you specify in the + request body will be updated. Note that the permission name itself cannot be + changed as it serves as the immutable identifier. This operation is useful + for maintaining clear documentation of permission purposes or updating + descriptions to reflect changes in system functionality. Returns the updated + permission object with modified timestamps. + tags: + - Permissions + summary: Update permission details + operationId: RolesService_UpdatePermission + parameters: + - schema: + type: string + description: Name of the permission + name: permission_name + in: path + required: true + responses: + '200': + description: >- + Permission updated successfully. Returns the modified permission object + with updated description and timestamps. + content: + application/json: + schema: + $ref: ../components/schemas/rolesUpdatePermissionResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_permissions_{permission_name}/put.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_permissions_{permission_name}/put.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_permissions_{permission_name}/put.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_permissions_{permission_name}/put.java + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/v1rolesCreatePermission.yaml + required: true +delete: + description: >- + Permanently removes a permission from the environment using its unique name + identifier. Use this endpoint when you need to clean up unused permissions + or remove access controls that are no longer relevant. The permission is + identified by its name in the path parameter following the format + 'action:resource'. This operation cannot be undone, so ensure no active + roles depend on the permission before deletion. If the permission is + currently assigned to any roles, you may need to remove those assignments + first or update the roles to use alternative permissions. Returns no content + on successful deletion. + tags: + - Permissions + summary: Delete permission + operationId: RolesService_DeletePermission + parameters: + - schema: + type: string + description: Name of the permission + name: permission_name + in: path + required: true + responses: + '200': + description: Permission successfully deleted. No content returned. + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_permissions_{permission_name}/delete.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_permissions_{permission_name}/delete.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_permissions_{permission_name}/delete.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_permissions_{permission_name}/delete.java diff --git a/openapi/paths/api_v1_roles.yaml b/openapi/paths/api_v1_roles.yaml new file mode 100644 index 000000000..f8a4e8689 --- /dev/null +++ b/openapi/paths/api_v1_roles.yaml @@ -0,0 +1,102 @@ +get: + description: >- + Retrieves a comprehensive list of all roles available within the specified + environment including organization roles. Use this endpoint to view all role + definitions, including custom roles and their configurations. You can + optionally include permission details for each role to understand their + capabilities. This is useful for role management, auditing organization + access controls, or understanding the available access levels within the + organization. + tags: + - Roles + summary: List all roles in environment + operationId: RolesService_ListRoles + parameters: + - schema: + type: string + description: >- + Include additional data in the response. Valid values: 'permissions' + (direct permissions only), 'permissions:all' (includes inherited + permissions from role hierarchy) + name: include + in: query + responses: + '200': + description: >- + Successfully retrieved list of roles. Returns all roles with their + metadata and optionally their permissions. + content: + application/json: + schema: + $ref: ../components/schemas/rolesListRolesResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_roles/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_roles/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_roles/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_roles/get.java +post: + description: >- + Creates a new role within the environment with specified permissions and + metadata. Use this endpoint to define custom roles that can be assigned to + users or groups. You can create hierarchical roles by extending existing + roles, assign specific permissions, and configure display information. Roles + are the foundation of your access control system and determine what actions + users can perform. + tags: + - Roles + summary: Create new role in environment + operationId: RolesService_CreateRole + responses: + '201': + description: >- + Role created successfully. Returns the complete role object with + system-generated ID and timestamps. + content: + application/json: + schema: + $ref: ../components/schemas/rolesCreateRoleResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_roles/post.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_roles/post.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_roles/post.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_roles/post.java + requestBody: + content: + application/json: + schema: + description: >- + Role configuration details including name, display name, + description, permissions, and inheritance settings. + $ref: ../components/schemas/v1rolesCreateRole.yaml + examples: + - description: Can edit content + display_name: Content Editor + name: content_editor + permissions: + - read:content + - write:content + required: true diff --git a/openapi/paths/api_v1_roles:set_defaults.yaml b/openapi/paths/api_v1_roles:set_defaults.yaml new file mode 100644 index 000000000..fcfd933f2 --- /dev/null +++ b/openapi/paths/api_v1_roles:set_defaults.yaml @@ -0,0 +1,43 @@ +patch: + description: >- + Updates the default creator and member roles for the current environment. + Use this endpoint to configure which roles are automatically assigned to new + users when they join the environment. You can specify role names for both + creator and member default roles. The system will validate that the + specified roles exist and update the environment settings accordingly. + Returns the updated default role objects including their complete role + information and permissions. + tags: + - Roles + summary: Set default creator and member roles + operationId: RolesService_UpdateDefaultRoles + responses: + '200': + description: Default roles updated successfully + content: + application/json: + schema: + $ref: ../components/schemas/rolesUpdateDefaultRolesResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_roles:set_defaults/patch.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_roles:set_defaults/patch.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_roles:set_defaults/patch.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_roles:set_defaults/patch.java + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/rolesUpdateDefaultRolesRequest.yaml + required: true diff --git a/openapi/paths/api_v1_roles_default.yaml b/openapi/paths/api_v1_roles_default.yaml new file mode 100644 index 000000000..622435335 --- /dev/null +++ b/openapi/paths/api_v1_roles_default.yaml @@ -0,0 +1,26 @@ +patch: + description: >- + Updates the default creator and member roles for the current environment. + Use this endpoint to configure which roles are automatically assigned to new + users when they join the environment. You can specify role names for both + creator and member default roles. The system will validate that the + specified roles exist and update the environment settings accordingly. + Returns the updated default role objects including their complete role + information and permissions. + tags: + - Roles + summary: Set default creator and member roles + operationId: RolesService_UpdateDefaultRoles2 + responses: + '200': + description: Default roles updated successfully + content: + application/json: + schema: + $ref: ../components/schemas/rolesUpdateDefaultRolesResponse.yaml + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/rolesUpdateDefaultRolesRequest.yaml + required: true diff --git a/openapi/paths/api_v1_roles_{role_name}.yaml b/openapi/paths/api_v1_roles_{role_name}.yaml new file mode 100644 index 000000000..991b7afd0 --- /dev/null +++ b/openapi/paths/api_v1_roles_{role_name}.yaml @@ -0,0 +1,166 @@ +get: + description: >- + Retrieves complete information for a specific role including metadata and + inheritance details (base role and dependent role count). Use this endpoint + to audit role configuration and understand the role's place in the + hierarchy. To view the role's permissions, use the ListRolePermissions + endpoint. + tags: + - Roles + summary: Get role details + operationId: RolesService_GetRole + parameters: + - schema: + type: string + description: >- + Unique name identifier of the role to retrieve. Must be alphanumeric + with underscores, 1-64 characters. + name: role_name + in: path + required: true + - schema: + type: string + description: >- + Include additional data in the response. Valid values: 'permissions' + (direct permissions only), 'permissions:all' (includes inherited + permissions from role hierarchy) + name: include + in: query + responses: + '200': + description: >- + Successfully retrieved role details. Returns the role object including + metadata and inheritance details. Permissions are not included. + content: + application/json: + schema: + $ref: ../components/schemas/rolesGetRoleResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_roles_{role_name}/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_roles_{role_name}/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_roles_{role_name}/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_roles_{role_name}/get.java +put: + description: >- + Modifies an existing role's properties including display name, description, + permissions, and inheritance. Use this endpoint to update role metadata, + change permission assignments, or modify role hierarchy. Only the fields you + specify will be updated, leaving other properties unchanged. When updating + permissions, the new list replaces all existing permissions for the role. + tags: + - Roles + summary: Update role information + operationId: RolesService_UpdateRole + parameters: + - schema: + type: string + description: >- + Unique name identifier of the role to update. Must be alphanumeric with + underscores, 1-64 characters. + name: role_name + in: path + required: true + responses: + '200': + description: >- + Role updated successfully. Returns the modified role object with updated + timestamps. + content: + application/json: + schema: + $ref: ../components/schemas/rolesUpdateRoleResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_roles_{role_name}/put.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_roles_{role_name}/put.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_roles_{role_name}/put.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_roles_{role_name}/put.java + requestBody: + content: + application/json: + schema: + description: Role fields to update. Only specified fields will be modified. + $ref: ../components/schemas/v1rolesUpdateRole.yaml + examples: + - description: Can edit and approve content + display_name: Senior Editor + required: true +delete: + description: >- + Permanently removes a role from the environment and reassigns users who had + that role to a different role. Use this endpoint when you need to clean up + unused roles or restructure your access control system. The role cannot be + deleted if it has dependent roles (roles that extend it) unless you specify + a replacement role. If users are assigned to the role being deleted, you + must provide a reassign_role_name to move those users to a different role + before deletion can proceed. This action cannot be undone, so ensure no + critical users depend on the role before deletion. + tags: + - Roles + summary: Delete role and reassign users + operationId: RolesService_DeleteRole + parameters: + - schema: + type: string + description: >- + Unique name identifier of the role to delete. Must be alphanumeric with + underscores, 1-64 characters. + name: role_name + in: path + required: true + - schema: + type: string + description: Role name to reassign users to when deleting this role + name: reassign_role_id + in: query + - schema: + type: string + description: Role name to reassign users to when deleting this role + name: reassign_role_name + in: query + responses: + '200': + description: Role successfully deleted and users reassigned. No content returned. + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_roles_{role_name}/delete.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_roles_{role_name}/delete.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_roles_{role_name}/delete.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_roles_{role_name}/delete.java diff --git a/openapi/paths/api_v1_roles_{role_name}_dependents.yaml b/openapi/paths/api_v1_roles_{role_name}_dependents.yaml new file mode 100644 index 000000000..007596263 --- /dev/null +++ b/openapi/paths/api_v1_roles_{role_name}_dependents.yaml @@ -0,0 +1,49 @@ +get: + description: >- + Retrieves all roles that directly extend the specified base role through + inheritance. Use this endpoint to understand the role hierarchy and identify + which roles inherit permissions from a particular base role. Provide the + base role name as a path parameter, and the response will include all + dependent roles with their metadata and permission information. This + operation is useful for auditing role inheritance relationships, + understanding the impact of changes to base roles, or managing role + hierarchies effectively. Returns a list of dependent role objects including + their names, display names, descriptions, and permission details. + tags: + - Roles + summary: List dependent roles + operationId: RolesService_ListDependentRoles + parameters: + - schema: + type: string + description: Name of the base role + name: role_name + in: path + required: true + responses: + '200': + description: >- + Successfully retrieved dependent roles. Returns a list of all roles that + extend the specified base role, including their metadata and permission + information. + content: + application/json: + schema: + $ref: ../components/schemas/rolesListDependentRolesResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_roles_{role_name}_dependents/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_roles_{role_name}_dependents/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_roles_{role_name}_dependents/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_roles_{role_name}_dependents/get.java diff --git a/openapi/paths/api_v1_roles_{role_name}_permissions.yaml b/openapi/paths/api_v1_roles_{role_name}_permissions.yaml new file mode 100644 index 000000000..5ea2242bc --- /dev/null +++ b/openapi/paths/api_v1_roles_{role_name}_permissions.yaml @@ -0,0 +1,107 @@ +get: + description: >- + Retrieves all permissions directly assigned to the specified role, excluding + permissions inherited from base roles. Use this endpoint to view the + explicit permission assignments for a role, which is useful for + understanding direct role capabilities, auditing permission assignments, or + managing role-permission relationships. Provide the role name as a path + parameter, and the response will include only the permissions that are + directly assigned to that role. This operation does not include inherited + permissions from role hierarchies - use ListEffectiveRolePermissions to see + the complete set of permissions including inheritance. Returns a list of + permission objects with their names, descriptions, and assignment metadata. + tags: + - Roles + summary: List permissions for role + operationId: RolesService_ListRolePermissions + parameters: + - schema: + type: string + description: Name of the role + name: role_name + in: path + required: true + responses: + '200': + description: >- + Successfully retrieved role permissions. Returns a list of all + permissions directly assigned to the specified role, excluding inherited + permissions. + content: + application/json: + schema: + $ref: ../components/schemas/rolesListRolePermissionsResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_roles_{role_name}_permissions/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_roles_{role_name}_permissions/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_roles_{role_name}_permissions/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_roles_{role_name}_permissions/get.java +post: + description: >- + Adds one or more permissions to the specified role while preserving existing + permission assignments. Use this endpoint to grant additional capabilities + to a role without affecting its current permission set. Provide the role + name as a path parameter and a list of permission names in the request body. + The system will validate that all specified permissions exist in the + environment and add them to the role. Existing permission assignments remain + unchanged, making this operation safe for incremental permission management. + This is useful for gradually expanding role capabilities or adding new + permissions as your system evolves. Returns the updated list of all + permissions now assigned to the role. + tags: + - Roles + summary: Add permissions to role + operationId: RolesService_AddPermissionsToRole + parameters: + - schema: + type: string + description: Name of the role + name: role_name + in: path + required: true + responses: + '200': + description: >- + Permissions added to role successfully. Returns the complete list of all + permissions now assigned to the role, including both existing and newly + added permissions. + content: + application/json: + schema: + $ref: ../components/schemas/rolesAddPermissionsToRoleResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_roles_{role_name}_permissions/post.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_roles_{role_name}_permissions/post.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_roles_{role_name}_permissions/post.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_roles_{role_name}_permissions/post.java + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/RolesServiceAddPermissionsToRoleBody.yaml + required: true diff --git a/openapi/paths/api_v1_roles_{role_name}_permissions:all.yaml b/openapi/paths/api_v1_roles_{role_name}_permissions:all.yaml new file mode 100644 index 000000000..715e98bf8 --- /dev/null +++ b/openapi/paths/api_v1_roles_{role_name}_permissions:all.yaml @@ -0,0 +1,34 @@ +get: + description: >- + Retrieves the complete set of effective permissions for a role, including + both directly assigned permissions and permissions inherited from base roles + through the role hierarchy. Use this endpoint to understand the full scope + of capabilities available to users assigned to a specific role. Provide the + role name as a path parameter, and the response will include all permissions + that apply to the role, accounting for inheritance relationships. This + operation is essential for auditing role capabilities, understanding + permission inheritance, or verifying the complete access scope before role + assignment. Returns a comprehensive list of permission names representing + the full set of effective permissions for the specified role. + tags: + - Roles + summary: List effective permissions for role + operationId: RolesService_ListEffectiveRolePermissions + parameters: + - schema: + type: string + description: Name of the role + name: role_name + in: path + required: true + responses: + '200': + description: >- + Successfully retrieved effective permissions. Returns the complete list + of all permissions that apply to the role, including both direct + assignments and inherited permissions from base roles. + content: + application/json: + schema: + $ref: >- + ../components/schemas/rolesListEffectiveRolePermissionsResponse.yaml diff --git a/openapi/paths/api_v1_roles_{role_name}_permissions_{permission_name}.yaml b/openapi/paths/api_v1_roles_{role_name}_permissions_{permission_name}.yaml new file mode 100644 index 000000000..9c8d07af1 --- /dev/null +++ b/openapi/paths/api_v1_roles_{role_name}_permissions_{permission_name}.yaml @@ -0,0 +1,56 @@ +delete: + description: >- + Removes a specific permission from the specified role, revoking that + capability from all users assigned to the role. Use this endpoint to + restrict role capabilities or remove unnecessary permissions. Provide both + the role name and permission name as path parameters. This operation only + affects the direct permission assignment and does not impact permissions + inherited from base roles. If the permission is inherited through role + hierarchy, you may need to modify the base role instead. This is useful for + fine-tuning role permissions, implementing least-privilege access controls, + or removing deprecated permissions. Returns no content on successful + removal. + tags: + - Roles + summary: Remove permission from role + operationId: RolesService_RemovePermissionFromRole + parameters: + - schema: + type: string + description: Name of the role + name: role_name + in: path + required: true + - schema: + type: string + description: Name of the permission to remove + name: permission_name + in: path + required: true + responses: + '200': + description: Permission removed from role successfully. No content returned. + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_roles_{role_name}_permissions_{permission_name}/delete.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_roles_{role_name}_permissions_{permission_name}/delete.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_roles_{role_name}_permissions_{permission_name}/delete.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_roles_{role_name}_permissions_{permission_name}/delete.java diff --git a/openapi/paths/api_v1_roles_{role_name}_users:count.yaml b/openapi/paths/api_v1_roles_{role_name}_users:count.yaml new file mode 100644 index 000000000..f872e0793 --- /dev/null +++ b/openapi/paths/api_v1_roles_{role_name}_users:count.yaml @@ -0,0 +1,49 @@ +get: + description: >- + Retrieves the total number of users currently assigned to the specified role + within the environment. Use this endpoint to monitor role usage, enforce + user limits, or understand the scope of role assignments. Provide the role's + unique name as a path parameter, and the response will include the current + user count for that role. This operation is read-only and does not modify + any data or user assignments. The count reflects all users who have the role + either directly assigned or inherited through organization membership. This + information is useful for capacity planning, security auditing, or + understanding the impact of role changes across your user base. + tags: + - Roles + summary: Retrieve user count for role + operationId: RolesService_GetRoleUsersCount + parameters: + - schema: + type: string + description: Unique name of the role + name: role_name + in: path + required: true + responses: + '200': + description: >- + Successfully retrieved user count for the specified role. Returns the + total number of users currently assigned to the role, including both + direct assignments and inherited assignments. + content: + application/json: + schema: + $ref: ../components/schemas/rolesGetRoleUsersCountResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_roles_{role_name}_users:count/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_roles_{role_name}_users:count/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_roles_{role_name}_users:count/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_roles_{role_name}_users:count/get.java diff --git a/openapi/paths/api_v1_sessions_{session_id}.yaml b/openapi/paths/api_v1_sessions_{session_id}.yaml new file mode 100644 index 000000000..2390e1a12 --- /dev/null +++ b/openapi/paths/api_v1_sessions_{session_id}.yaml @@ -0,0 +1,46 @@ +get: + description: >- + Retrieves comprehensive details for a specific user session including + authentication status, device information, and expiration timelines. Use + this endpoint to fetch current session metadata for security audits, session + validation, or to display session information in user account management + interfaces. Returns all session properties including the user ID, + authenticated organizations, device details with browser/OS information, IP + address and geolocation, and all relevant timestamps (creation, last + activity, idle expiration, absolute expiration, and actual expiration if + applicable). + tags: + - Sessions + summary: Get session details + operationId: SessionService_GetSession + parameters: + - schema: + type: string + description: Unique identifier for the session. Must start with 'ses_' prefix. + name: session_id + in: path + required: true + responses: + '200': + description: Successfully retrieved session details + content: + application/json: + schema: + $ref: ../components/schemas/sessionsSessionDetails.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_sessions_{session_id}/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_sessions_{session_id}/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_sessions_{session_id}/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_sessions_{session_id}/get.java diff --git a/openapi/paths/api_v1_sessions_{session_id}_revoke.yaml b/openapi/paths/api_v1_sessions_{session_id}_revoke.yaml new file mode 100644 index 000000000..b587aad4f --- /dev/null +++ b/openapi/paths/api_v1_sessions_{session_id}_revoke.yaml @@ -0,0 +1,46 @@ +post: + description: >- + Immediately invalidates a specific user session by session ID, setting its + status to 'revoked'. Once revoked, the session cannot be used for any future + API requests or application access. Use this endpoint to implement + session-level logout, force a user to reauthenticate on a specific device, + or terminate suspicious sessions. The revocation is instantaneous and + irreversible. Returns the revoked session details including the session ID, + user ID, and the revocation timestamp. + tags: + - Sessions + summary: Revoke user session + operationId: SessionService_RevokeSession + parameters: + - schema: + type: string + description: >- + Unique identifier for the session to revoke. Must start with 'ses_' + prefix. + name: session_id + in: path + required: true + responses: + '200': + description: Successfully revoked the session. Returns the revoked session details + content: + application/json: + schema: + $ref: ../components/schemas/sessionsRevokeSessionResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_sessions_{session_id}_revoke/post.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_sessions_{session_id}_revoke/post.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_sessions_{session_id}_revoke/post.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_sessions_{session_id}_revoke/post.java diff --git a/openapi/paths/api_v1_users.yaml b/openapi/paths/api_v1_users.yaml new file mode 100644 index 000000000..f75c0be24 --- /dev/null +++ b/openapi/paths/api_v1_users.yaml @@ -0,0 +1,51 @@ +get: + description: >- + Retrieves a paginated list of all users across your entire environment. Use + this endpoint to view all users regardless of their organization + memberships. This is useful for administrative purposes, user audits, or + when you need to see all users in your Scalekit environment. Supports + pagination for large user bases. + tags: + - Users + summary: List all users in environment + operationId: UserService_ListUsers + parameters: + - schema: + type: integer + format: int64 + description: >- + Maximum number of organizations to return per page. Must be between 10 + and 100 + name: page_size + in: query + - schema: + type: string + description: >- + Pagination token from the previous response. Use to retrieve the next + page of organizations + name: page_token + in: query + responses: + '200': + description: List of users. + content: + application/json: + schema: + $ref: ../components/schemas/usersListUsersResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_users/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_users/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_users/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_users/get.java diff --git a/openapi/paths/api_v1_users:search.yaml b/openapi/paths/api_v1_users:search.yaml new file mode 100644 index 000000000..3bc4e3c4b --- /dev/null +++ b/openapi/paths/api_v1_users:search.yaml @@ -0,0 +1,55 @@ +get: + description: >- + Searches for users across the entire environment by email address, user ID, + or external ID. The query must be at least 3 characters and is + case-insensitive. Returns a paginated list of matching users with up to 30 + results per page. Use the next_page_token from the response to retrieve + subsequent pages. + tags: + - Users + summary: Search users + operationId: UserService_SearchUsers + parameters: + - schema: + type: string + minLength: 3 + maxLength: 100 + description: >- + Search term to match against user email, IDs, or external IDs. Must be + at least 3 characters. Case insensitive. + name: query + in: query + required: true + - schema: + type: integer + format: int64 + minimum: 1 + maximum: 30 + description: >- + Maximum number of users to return per page. Value must be between 1 and + 30. + name: page_size + in: query + - schema: + type: string + description: >- + Token from a previous response for pagination. Provide this to retrieve + the next page of results. + name: page_token + in: query + responses: + '200': + description: >- + Matching users returned; includes pagination cursors for navigating + large result sets. + content: + application/json: + schema: + $ref: ../components/schemas/usersSearchUsersResponse.yaml + '400': + description: >- + Bad Request - query must be at least 3 characters and no more than 100 + characters. + content: + application/json: + schema: {} diff --git a/openapi/paths/api_v1_users_{id}.yaml b/openapi/paths/api_v1_users_{id}.yaml new file mode 100644 index 000000000..fce69d74e --- /dev/null +++ b/openapi/paths/api_v1_users_{id}.yaml @@ -0,0 +1,161 @@ +get: + description: >- + Retrieves all details for a user by system-generated user ID or external ID. + The response includes organization memberships and user metadata. + tags: + - Users + summary: Get user + operationId: UserService_GetUser + parameters: + - schema: + type: string + description: System-generated user ID + name: id + in: path + required: true + - schema: + type: string + description: >- + Your application's unique identifier for this organization, used to link + Scalekit with your system. + name: external_id + in: query + responses: + '200': + description: >- + User details retrieved successfully. Returns full user object with + system-generated fields and timestamps. + content: + application/json: + schema: + $ref: ../components/schemas/usersGetUserResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_users_{id}/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_users_{id}/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_users_{id}/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_users_{id}/get.java +delete: + description: >- + Permanently removes a user from your environment and deletes all associated + data. Use this endpoint when you need to completely remove a user account. + This action deletes the user's profile, memberships, and all related data + across all organizations. This operation cannot be undone, so use with + caution. + tags: + - Users + summary: Delete user permanently + operationId: UserService_DeleteUser + parameters: + - schema: + type: string + description: System-generated user ID. Must start with 'usr_' (19-25 characters) + name: id + in: path + required: true + - schema: + type: string + description: >- + External system identifier from connected directories. Must match + existing records + name: external_id + in: query + responses: + '200': + description: User successfully deleted. No content returned + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_users_{id}/delete.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_users_{id}/delete.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_users_{id}/delete.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_users_{id}/delete.java +patch: + description: >- + Modifies user account information including profile details, metadata, and + external ID. Use this endpoint to update a user's personal information, + contact details, or custom metadata. You can update the user's profile, + phone number, and metadata fields. Note that fields like user ID, email + address, environment ID, and creation time cannot be modified. + tags: + - Users + summary: Update user information + operationId: UserService_UpdateUser + parameters: + - schema: + type: string + description: >- + System-generated user ID. Must start with 'usr_' and be 19-25 characters + long. + name: id + in: path + required: true + - schema: + type: string + description: >- + Your application's unique identifier for this organization, used to link + Scalekit with your system. + name: external_id + in: query + responses: + '200': + description: >- + User updated successfully. Returns the modified user object with updated + timestamps. + content: + application/json: + schema: + $ref: ../components/schemas/usersUpdateUserResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_users_{id}/patch.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_users_{id}/patch.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_users_{id}/patch.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_users_{id}/patch.java + requestBody: + content: + application/json: + schema: + description: >- + User fields to update. Only specified fields will be modified. + Required fields must be provided if being changed. + $ref: ../components/schemas/v1usersUpdateUser.yaml + examples: + - firstName: John + lastName: Doe + required: true diff --git a/openapi/paths/api_v1_users_{user_id}_sessions.yaml b/openapi/paths/api_v1_users_{user_id}_sessions.yaml new file mode 100644 index 000000000..1633611f9 --- /dev/null +++ b/openapi/paths/api_v1_users_{user_id}_sessions.yaml @@ -0,0 +1,97 @@ +get: + description: >- + Retrieves a paginated list of all sessions associated with a specific user + across all devices and browsers. Use this endpoint to audit user activity, + display all active sessions in account management interfaces, or verify user + authentication status across devices. Supports filtering by session status + (active, expired, revoked, logout) and time range (creation date). Returns + session details for each session including device information, IP address, + geolocation, and current status. The response includes pagination metadata + (page tokens and total count) to handle large session lists efficiently. + tags: + - Sessions + summary: List user sessions + operationId: SessionService_GetUserSessions + parameters: + - schema: + type: string + description: >- + Unique identifier for the user whose sessions to retrieve. Must start + with 'usr_' prefix. + name: user_id + in: path + required: true + - schema: + type: integer + format: int64 + description: >- + Maximum number of sessions to return in a single page. Optional + parameter. If not specified, defaults to a server-defined limit. Use + smaller values for faster responses, larger values for fewer requests. + name: page_size + in: query + - schema: + type: string + description: >- + Pagination token from the previous response for retrieving the next page + of results. Leave empty for the first page. Use the next_page_token from + a previous response to fetch subsequent pages. + name: page_token + in: query + - schema: + type: array + items: + type: string + style: form + explode: true + description: >- + Filter sessions by one or more status values. Possible values: 'active', + 'expired', 'revoked', 'logout'. Leave empty to include all statuses. + Multiple values use OR logic (e.g., status=['active', 'expired'] returns + sessions that are either active OR expired). + name: filter.status + in: query + - schema: + type: string + format: date-time + description: >- + Filter to include only sessions created on or after this timestamp. + Optional. Uses RFC 3339 format. Useful for querying sessions within a + specific time window. + name: filter.start_time + in: query + - schema: + type: string + format: date-time + description: >- + Filter to include only sessions created on or before this timestamp. + Optional. Uses RFC 3339 format. Must be after start_time if both are + specified. + name: filter.end_time + in: query + responses: + '200': + description: >- + Successfully retrieved user sessions. Returns a list of sessions with + pagination information + content: + application/json: + schema: + $ref: ../components/schemas/sessionsUserSessionDetails.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_users_{user_id}_sessions/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_users_{user_id}_sessions/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_users_{user_id}_sessions/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_users_{user_id}_sessions/get.java diff --git a/openapi/paths/api_v1_users_{user_id}_sessions_revoke.yaml b/openapi/paths/api_v1_users_{user_id}_sessions_revoke.yaml new file mode 100644 index 000000000..51420519f --- /dev/null +++ b/openapi/paths/api_v1_users_{user_id}_sessions_revoke.yaml @@ -0,0 +1,50 @@ +post: + description: >- + Immediately invalidates all active sessions for a specific user across all + devices and browsers, setting their status to 'revoked'. Use this endpoint + to implement global logout functionality, force re-authentication after + security incidents, or terminate all sessions following a password reset or + credential compromise. Only active sessions are revoked; already expired, + logout, or previously revoked sessions remain unchanged. The revocation is + atomic and instantaneous. Returns a list of all revoked sessions with their + details and a total count of sessions revoked. + tags: + - Sessions + summary: Revoke all user sessions + operationId: SessionService_RevokeAllUserSessions + parameters: + - schema: + type: string + description: >- + Unique identifier for the user whose all sessions will be revoked. Must + start with 'usr_' prefix. + name: user_id + in: path + required: true + responses: + '200': + description: >- + Successfully revoked all user sessions. Returns the list of revoked + sessions and total count + content: + application/json: + schema: + $ref: ../components/schemas/sessionsRevokeAllUserSessionsResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_users_{user_id}_sessions_revoke/post.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_users_{user_id}_sessions_revoke/post.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_users_{user_id}_sessions_revoke/post.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_users_{user_id}_sessions_revoke/post.java diff --git a/openapi/paths/api_v1_webauthn_credentials.yaml b/openapi/paths/api_v1_webauthn_credentials.yaml new file mode 100644 index 000000000..e6e57974f --- /dev/null +++ b/openapi/paths/api_v1_webauthn_credentials.yaml @@ -0,0 +1,39 @@ +get: + description: >- + Retrieves all registered passkeys for the current user, including device + information, creation timestamps, and display names. Use this to show users + their registered authenticators. + tags: + - Passkeys + summary: List user's passkeys + operationId: WebAuthnService_ListCredentials + parameters: + - schema: + type: string + description: User ID to list credentials for (optional, current user if not provided) + name: user_id + in: query + responses: + '200': + description: List of passkeys with metadata + content: + application/json: + schema: + $ref: ../components/schemas/webauthnListCredentialsResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: ../code_samples/javascript/api_v1_webauthn_credentials/get.js + - label: Python SDK + lang: python + source: + $ref: ../code_samples/python/api_v1_webauthn_credentials/get.py + - label: Go SDK + lang: go + source: + $ref: ../code_samples/go/api_v1_webauthn_credentials/get.go + - label: Java SDK + lang: java + source: + $ref: ../code_samples/java/api_v1_webauthn_credentials/get.java diff --git a/openapi/paths/api_v1_webauthn_credentials_{credential_id}.yaml b/openapi/paths/api_v1_webauthn_credentials_{credential_id}.yaml new file mode 100644 index 000000000..3dab9075f --- /dev/null +++ b/openapi/paths/api_v1_webauthn_credentials_{credential_id}.yaml @@ -0,0 +1,92 @@ +delete: + description: >- + Deletes a specific passkey credential for the current user. After removal, + the authenticator can no longer be used for authentication. + tags: + - Passkeys + summary: Remove a passkey + operationId: WebAuthnService_DeleteCredential + parameters: + - schema: + type: string + description: The credential ID to delete + name: credential_id + in: path + required: true + responses: + '200': + description: Passkey successfully deleted + content: + application/json: + schema: + $ref: ../components/schemas/webauthnDeleteCredentialResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_webauthn_credentials_{credential_id}/delete.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_webauthn_credentials_{credential_id}/delete.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_webauthn_credentials_{credential_id}/delete.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_webauthn_credentials_{credential_id}/delete.java +patch: + description: >- + Updates the display name of a passkey credential to help users identify + their authenticators. Only the display name can be modified. + tags: + - Passkeys + summary: Rename a passkey + operationId: WebAuthnService_UpdateCredential + parameters: + - schema: + type: string + description: The credential ID to update + name: credential_id + in: path + required: true + responses: + '200': + description: Passkey successfully updated with new name + content: + application/json: + schema: + $ref: ../components/schemas/webauthnUpdateCredentialResponse.yaml + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: + $ref: >- + ../code_samples/javascript/api_v1_webauthn_credentials_{credential_id}/patch.js + - label: Python SDK + lang: python + source: + $ref: >- + ../code_samples/python/api_v1_webauthn_credentials_{credential_id}/patch.py + - label: Go SDK + lang: go + source: + $ref: >- + ../code_samples/go/api_v1_webauthn_credentials_{credential_id}/patch.go + - label: Java SDK + lang: java + source: + $ref: >- + ../code_samples/java/api_v1_webauthn_credentials_{credential_id}/patch.java + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/WebAuthnServiceUpdateCredentialBody.yaml + required: true diff --git a/openapi/saaskit.yaml b/openapi/saaskit.yaml new file mode 100644 index 000000000..c46192866 --- /dev/null +++ b/openapi/saaskit.yaml @@ -0,0 +1,374 @@ +info: + description: "# Overview\n\nThe Scalekit API is a RESTful API that enables you to manage organizations, users, and authentication settings. All requests must use HTTPS.\nAll API requests use the following base URLs:\n\n```\nhttps://{your-subdomain}.scalekit.dev (Development)\nhttps://{your-subdomain}.scalekit.com (Production)\nhttps://auth.yourapp.com (Custom domain)\n```\n\nScalekit operates two separate environments: Development and Production. Resources cannot be moved between environments.\n\n## Quickstart\n\nThe Scalekit API uses OAuth 2.0 Client Credentials for authentication.\n\nCopy your API credentials from the Scalekit dashboard's API Config section and set them as environment variables.\n\n```sh\nSCALEKIT_ENVIRONMENT_URL=''\nSCALEKIT_CLIENT_ID=''\nSCALEKIT_CLIENT_SECRET=''\n```\n\nGetting an access token\n\n1. Get your credentials from the [Scalekit Dashboard](https://app.scalekit.com)\n2. Request an access token:\n\n```sh\ncurl https:///oauth/token \\\n -X POST \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d 'client_id={client_id}' \\\n -d 'client_secret={client_secret}' \\\n -d 'grant_type=client_credentials'\n```\n\n3. Use the access token in API requests:\n\n```sh\ncurl https:///api/v1/organizations \\\n -H 'Content-Type: application/json' \\\n -H 'Authorization: Bearer {access_token}'\n```\n\nThe response includes an access token:\n\n```json\n{\n\t\"access_token\": \"eyJhbGciOiJSUzI1NiIsImtpZCI6InNua181Ok4OTEyMjU2NiIsInR5cCI6IkpXVCJ9...\",\n\t\"token_type\": \"Bearer\",\n\t\"expires_in\": 86399,\n\t\"scope\": \"openid\"\n}\n```\n\n## SDKs\n\nScalekit provides official SDKs for multiple programming languages. Check the changelog at GitHub repositories for the latest updates.\n\n### Node.js\n\n```sh\nnpm install @scalekit-sdk/node\n```\n\nCreate a new Scalekit client instance after initializing the environment variables\n\n```js\nimport { Scalekit } from \"@scalekit-sdk/node\";\n\nexport let scalekit = new Scalekit(\n\tprocess.env.SCALEKIT_ENVIRONMENT_URL,\n\tprocess.env.SCALEKIT_CLIENT_ID,\n\tprocess.env.SCALEKIT_CLIENT_SECRET\n);\n```\n\n[See the Node SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-node/releases)\n\n### Python\n\n```sh\npip install scalekit-sdk-python\n```\n\nCreate a new Scalekit client instance after initializing the environment variables.\n\n```py\nfrom scalekit import ScalekitClient\nimport os\n\nscalekit_client = ScalekitClient(\n os.environ.get('SCALEKIT_ENVIRONMENT_URL'),\n os.environ.get('SCALEKIT_CLIENT_ID'),\n os.environ.get('SCALEKIT_CLIENT_SECRET')\n)\n```\n\n[See the Python SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-python/releases)\n\n### Go\n\n```sh\ngo get -u github.com/scalekit-inc/scalekit-sdk-go\n```\n\nCreate a new Scalekit client instance after initializing the environment variables.\n\n```go\npackage main\n\nimport (\n \"os\"\n \"github.com/scalekit-inc/scalekit-sdk-go\"\n)\n\nscalekitClient := scalekit.NewScalekitClient(\n os.Getenv(\"SCALEKIT_ENVIRONMENT_URL\"),\n os.Getenv(\"SCALEKIT_CLIENT_ID\"),\n os.Getenv(\"SCALEKIT_CLIENT_SECRET\"),\n)\n```\n\n[See the Go SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-go/releases)\n\n### Java\n\n```gradle\n/* Gradle users - add the following to your dependencies in build file */\nimplementation \"com.scalekit:scalekit-sdk-java:2.0.11\"\n```\n\n```xml\n\n\n com.scalekit\n scalekit-sdk-java\n 2.0.11\n\n```\n\n[See the Java SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-java/releases)\n\n### Error handling\n\nThe API uses standard HTTP status codes:\n\n| Code | Description |\n| ----------- | -------------------- |\n| 200/201 | Success |\n| 400 | Invalid request |\n| 401 | Authentication error |\n| 404 | Resource not found |\n| 429 | Rate limit exceeded |\n| 500/501/504 | Server error |\n\nError responses include detailed information:\n\n```json\n{\n\t\"code\": 16,\n\t\"message\": \"Token empty\",\n\t\"details\": [\n\t\t{\n\t\t\t\"@type\": \"type.googleapis.com/scalekit.v1.errdetails.ErrorInfo\",\n\t\t\t\"error_code\": \"UNAUTHENTICATED\"\n\t\t}\n\t]\n}\n```\n\n---\n\nBuilding AI agents that need OAuth tokens, tool execution, or connected accounts? See the [AgentKit API reference](https://docs.scalekit.com/agentkit/apis/). For the complete endpoint list across both products, see [All APIs](https://docs.scalekit.com/apis/).\n" + title: SaaSKit APIs + contact: + name: Scalekit Inc + url: https://scalekit.com + email: support@scalekit.com + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0 + version: 1.0.0 + x-scalar-sdk-installation: + - lang: shell + description: >- + Set up OAuth 2.0 Client Credentials authentication to access Scalekit + APIs. Includes credential configuration, token exchange, and + authenticated API request examples. + source: > + + # 1. Obtain API Credentials + + # Get your credentials from the Scalekit dashboard + + export SCALEKIT_ENVIRONMENT_URL="https://your-org.scalekit.dev" # Your + Scalekit environment URL + + export SCALEKIT_CLIENT_ID="your_client_id" # Your + client ID + + export SCALEKIT_CLIENT_SECRET="your_client_secret" # Your + client secret + + + # 2. Exchange client credentials an OAuth 2.0 access token + + TOKEN_RESPONSE=$(curl -s -X POST + "${SCALEKIT_ENVIRONMENT_URL}/oauth/token" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "client_id=${SCALEKIT_CLIENT_ID}" \ + -d "client_secret=${SCALEKIT_CLIENT_SECRET}" \ + -d "grant_type=client_credentials") + + # 3. Make Authenticated API Requests + + curl -X GET "${SCALEKIT_ENVIRONMENT_URL}/api/v1/organizations" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${ACCESS_TOKEN}" \ + -H "Accept: application/json" +paths: + /api/v1/connections: + $ref: paths/api_v1_connections.yaml + /api/v1/invites/organizations/{organization_id}/users/{id}/resend: + $ref: >- + paths/api_v1_invites_organizations_{organization_id}_users_{id}_resend.yaml + /api/v1/memberships/organizations/{organization_id}/users/{id}: + $ref: paths/api_v1_memberships_organizations_{organization_id}_users_{id}.yaml + /api/v1/organizations: + $ref: paths/api_v1_organizations.yaml + /api/v1/organizations/{id}: + $ref: paths/api_v1_organizations_{id}.yaml + /api/v1/organizations/{id}/portal_links: + $ref: paths/api_v1_organizations_{id}_portal_links.yaml + /api/v1/organizations/{id}/settings: + $ref: paths/api_v1_organizations_{id}_settings.yaml + /api/v1/organizations/{org_id}/roles: + $ref: paths/api_v1_organizations_{org_id}_roles.yaml + /api/v1/organizations/{org_id}/roles/{role_name}: + $ref: paths/api_v1_organizations_{org_id}_roles_{role_name}.yaml + /api/v1/organizations/{org_id}/roles:set_defaults: + $ref: paths/api_v1_organizations_{org_id}_roles:set_defaults.yaml + /api/v1/organizations/{organization_id}/clients: + $ref: paths/api_v1_organizations_{organization_id}_clients.yaml + /api/v1/organizations/{organization_id}/clients/{client_id}: + $ref: paths/api_v1_organizations_{organization_id}_clients_{client_id}.yaml + /api/v1/organizations/{organization_id}/clients/{client_id}/secrets: + $ref: >- + paths/api_v1_organizations_{organization_id}_clients_{client_id}_secrets.yaml + /api/v1/organizations/{organization_id}/clients/{client_id}/secrets/{secret_id}: + $ref: >- + paths/api_v1_organizations_{organization_id}_clients_{client_id}_secrets_{secret_id}.yaml + /api/v1/organizations/{organization_id}/connections/{id}: + $ref: paths/api_v1_organizations_{organization_id}_connections_{id}.yaml + /api/v1/organizations/{organization_id}/connections/{id}:disable: + $ref: paths/api_v1_organizations_{organization_id}_connections_{id}:disable.yaml + /api/v1/organizations/{organization_id}/connections/{id}:enable: + $ref: paths/api_v1_organizations_{organization_id}_connections_{id}:enable.yaml + /api/v1/organizations/{organization_id}/directories: + $ref: paths/api_v1_organizations_{organization_id}_directories.yaml + /api/v1/organizations/{organization_id}/directories/{directory_id}/groups: + $ref: >- + paths/api_v1_organizations_{organization_id}_directories_{directory_id}_groups.yaml + /api/v1/organizations/{organization_id}/directories/{directory_id}/users: + $ref: >- + paths/api_v1_organizations_{organization_id}_directories_{directory_id}_users.yaml + /api/v1/organizations/{organization_id}/directories/{id}: + $ref: paths/api_v1_organizations_{organization_id}_directories_{id}.yaml + /api/v1/organizations/{organization_id}/directories/{id}:disable: + $ref: paths/api_v1_organizations_{organization_id}_directories_{id}:disable.yaml + /api/v1/organizations/{organization_id}/directories/{id}:enable: + $ref: paths/api_v1_organizations_{organization_id}_directories_{id}:enable.yaml + /api/v1/organizations/{organization_id}/domains: + $ref: paths/api_v1_organizations_{organization_id}_domains.yaml + /api/v1/organizations/{organization_id}/domains/{id}: + $ref: paths/api_v1_organizations_{organization_id}_domains_{id}.yaml + /api/v1/organizations/{organization_id}/session-policy: + $ref: paths/api_v1_organizations_{organization_id}_session-policy.yaml + /api/v1/organizations/{organization_id}/settings/usermanagement: + $ref: paths/api_v1_organizations_{organization_id}_settings_usermanagement.yaml + /api/v1/organizations/{organization_id}/users: + $ref: paths/api_v1_organizations_{organization_id}_users.yaml + /api/v1/organizations/{organization_id}/users/{user_id}/permissions: + $ref: >- + paths/api_v1_organizations_{organization_id}_users_{user_id}_permissions.yaml + /api/v1/organizations/{organization_id}/users/{user_id}/roles: + $ref: paths/api_v1_organizations_{organization_id}_users_{user_id}_roles.yaml + /api/v1/organizations/{organization_id}/users:search: + $ref: paths/api_v1_organizations_{organization_id}_users:search.yaml + /api/v1/organizations:external/{external_id}: + $ref: paths/api_v1_organizations:external_{external_id}.yaml + /api/v1/passwordless/email/resend: + $ref: paths/api_v1_passwordless_email_resend.yaml + /api/v1/passwordless/email/send: + $ref: paths/api_v1_passwordless_email_send.yaml + /api/v1/passwordless/email/verify: + $ref: paths/api_v1_passwordless_email_verify.yaml + /api/v1/permissions: + $ref: paths/api_v1_permissions.yaml + /api/v1/permissions/{permission_name}: + $ref: paths/api_v1_permissions_{permission_name}.yaml + /api/v1/roles: + $ref: paths/api_v1_roles.yaml + /api/v1/roles/default: + $ref: paths/api_v1_roles_default.yaml + /api/v1/roles/{role_name}: + $ref: paths/api_v1_roles_{role_name}.yaml + /api/v1/roles/{role_name}/dependents: + $ref: paths/api_v1_roles_{role_name}_dependents.yaml + /api/v1/roles/{role_name}/permissions: + $ref: paths/api_v1_roles_{role_name}_permissions.yaml + /api/v1/roles/{role_name}/permissions/{permission_name}: + $ref: paths/api_v1_roles_{role_name}_permissions_{permission_name}.yaml + /api/v1/roles/{role_name}/permissions:all: + $ref: paths/api_v1_roles_{role_name}_permissions:all.yaml + /api/v1/roles/{role_name}/users:count: + $ref: paths/api_v1_roles_{role_name}_users:count.yaml + /api/v1/roles:set_defaults: + $ref: paths/api_v1_roles:set_defaults.yaml + /api/v1/sessions/{session_id}: + $ref: paths/api_v1_sessions_{session_id}.yaml + /api/v1/sessions/{session_id}/revoke: + $ref: paths/api_v1_sessions_{session_id}_revoke.yaml + /api/v1/users: + $ref: paths/api_v1_users.yaml + /api/v1/users/{id}: + $ref: paths/api_v1_users_{id}.yaml + /api/v1/users/{user_id}/sessions: + $ref: paths/api_v1_users_{user_id}_sessions.yaml + /api/v1/users/{user_id}/sessions/revoke: + $ref: paths/api_v1_users_{user_id}_sessions_revoke.yaml + /api/v1/users:search: + $ref: paths/api_v1_users:search.yaml + /api/v1/webauthn/credentials: + $ref: paths/api_v1_webauthn_credentials.yaml + /api/v1/webauthn/credentials/{credential_id}: + $ref: paths/api_v1_webauthn_credentials_{credential_id}.yaml +tags: + - description: > + Organization represents a customer or a tenant of your product. This is + the top level entity and all resources are mapped to this Organization + object. Each organization is uniquely identified by `organization_id`. + + + + name: Organizations + - description: >- + Permission management for defining and controlling access to system + resources. Create, retrieve, update, and delete granular permissions that + represent specific actions users can perform. Permissions are the building + blocks of role-based access control (RBAC) and can be assigned to roles to + grant users the ability to perform specific operations. Use this service + to define custom permissions for your application's unique access control + requirements. + name: Permissions + - description: >- + Comprehensive user management operations including user lifecycle, + organization memberships, and invitation workflows. This service provides + endpoints for creating, retrieving, updating, and deleting user accounts + across your Scalekit environment. It supports both individual user + operations and bulk operations for user administration, including user + search, pagination, and metadata management. The service also handles user + invitations and organization membership management. + name: Users + - description: >- + Manage enterprise connections for your Scalekit environment. This service + provides endpoints for retrieving, and updating connections. + name: Connections + - description: >- + Directory management for viewing and controlling external identity + provider connections in your Scalekit environment. This service provides + endpoints for retrieving directory information, listing directories and + their contents, and enabling or disabling directory synchronization. + name: Directory + - description: >- + Role-based access control (RBAC) for defining and managing permissions in + an environment. Create and update custom roles with explicit permissions, + model role hierarchies through inheritance, view dependent roles, manage + role-permission assignments, and list roles and permissions. Also provides + a utility to count users assigned to a role. + name: Roles + - description: >- + Comprehensive session management for user authentication and + authorization. This service provides endpoints for retrieving session + details, managing user sessions across devices, revoking individual + sessions, and terminating all active sessions for a user. It supports + session auditing, device tracking, and security monitoring with detailed + session metadata including device information, IP geolocation, and + activity timestamps. + name: Sessions + - description: > + Manage organization-level domains. Scalekit supports two domain types: + + + - ORGANIZATION_DOMAIN: Used for SSO domain discovery. When a user signs in + with a matching email domain, Scalekit routes them to the organization’s + SSO provider and enforces SSO. + + - ALLOWED_EMAIL_DOMAIN: Used to mark trusted email domains for an + organization. When a user signs in or signs up with a matching domain, + Scalekit suggests the organization in the organization switcher + (authentication-method agnostic). + name: Domains + - description: >- + Endpoints for managing API client applications. API clients enable secure, + automated interactions between software systems without human + intervention. Each client is uniquely identified by a `client_id` and can + be configured with authentication settings, redirect URIs, and security + parameters. Use these endpoints to create, manage, and configure API + clients for your API clients. + name: API Auth + externalDocs: + url: https://docs.scalekit.com/m2m/overview + - description: >- + Endpoints for sending and verifying passwordless authentication emails. + These APIs allow users to authenticate without passwords by receiving a + verification code or magic link in their email. + name: Magic link & OTP + - description: Endpoints for passkey-based authentication using WebAuthn/FIDO2 standards. + name: Passkeys + +externalDocs: + description: Scalekit Docs + url: https://docs.scalekit.com/ +openapi: 3.1.1 +servers: + - url: https://$SCALEKIT_ENVIRONMENT_URL +components: + securitySchemes: + oauth2: + type: oauth2 + flows: + clientCredentials: + tokenUrl: https://$SCALEKIT_ENVIRONMENT_URL/oauth/token + scopes: + '': No scope required for client credentials flow +x-scalar-environments: + production: + variables: + SCALEKIT_ENVIRONMENT_URL: + default: https://$SCALEKIT_ENVIRONMENT_URL + description: yourapp.scalekit.com + staging: + variables: + SCALEKIT_ENVIRONMENT_URL: + default: https://$SCALEKIT_ENVIRONMENT_URL + description: yourapp.scalekit.dev +x-scalar-active-environment: staging +security: + - oauth2: [] +webhooks: + organization.created: + $ref: webhooks/organization.created.yaml + organization.updated: + $ref: webhooks/organization.updated.yaml + organization.deleted: + $ref: webhooks/organization.deleted.yaml + user.signup: + $ref: webhooks/user.signup.yaml + user.login: + $ref: webhooks/user.login.yaml + user.logout: + $ref: webhooks/user.logout.yaml + user.organization_invitation: + $ref: webhooks/user.organization_invitation.yaml + user.organization_membership_created: + $ref: webhooks/user.organization_membership_created.yaml + user.organization_membership_deleted: + $ref: webhooks/user.organization_membership_deleted.yaml + user.organization_membership_updated: + $ref: webhooks/user.organization_membership_updated.yaml + organization.directory_enabled: + $ref: webhooks/organization.directory_enabled.yaml + organization.directory_disabled: + $ref: webhooks/organization.directory_disabled.yaml + organization.directory.user_created: + $ref: webhooks/organization.directory.user_created.yaml + organization.directory.user_updated: + $ref: webhooks/organization.directory.user_updated.yaml + organization.directory.user_deleted: + $ref: webhooks/organization.directory.user_deleted.yaml + organization.directory.group_created: + $ref: webhooks/organization.directory.group_created.yaml + organization.directory.group_updated: + $ref: webhooks/organization.directory.group_updated.yaml + organization.directory.group_deleted: + $ref: webhooks/organization.directory.group_deleted.yaml + organization.sso_created: + $ref: webhooks/organization.sso_created.yaml + organization.sso_enabled: + $ref: webhooks/organization.sso_enabled.yaml + organization.sso_disabled: + $ref: webhooks/organization.sso_disabled.yaml + organization.sso_deleted: + $ref: webhooks/organization.sso_deleted.yaml + role.created: + $ref: webhooks/role.created.yaml + role.updated: + $ref: webhooks/role.updated.yaml + role.deleted: + $ref: webhooks/role.deleted.yaml + permission.created: + $ref: webhooks/permission.created.yaml + permission.updated: + $ref: webhooks/permission.updated.yaml + permission.deleted: + $ref: webhooks/permission.deleted.yaml + diff --git a/openapi/webhooks/connected_account.created.yaml b/openapi/webhooks/connected_account.created.yaml new file mode 100644 index 000000000..4225a519e --- /dev/null +++ b/openapi/webhooks/connected_account.created.yaml @@ -0,0 +1,25 @@ +post: + summary: Connected Account Created + description: Triggered when a new connected account is created + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_101531404017336586 + type: connected_account.created + object: ConnectedAccount + occurred_at: '2025-12-01T10:23:52.702980847Z' + environment_id: env_88640229614813449 + data: + authorization_type: OAUTH + connection_id: conn_100668583155073286 + id: ca_101531404000559370 + identifier: Bruce + provider: CANVA + status: PENDING_AUTH + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/connected_account.deleted.yaml b/openapi/webhooks/connected_account.deleted.yaml new file mode 100644 index 000000000..2ae5f5856 --- /dev/null +++ b/openapi/webhooks/connected_account.deleted.yaml @@ -0,0 +1,28 @@ +post: + summary: Connected Account Deleted + description: Triggered when a connected account is deleted + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_101653010731500290 + type: connected_account.deleted + object: ConnectedAccount + occurred_at: '2025-12-02T06:31:55.954027187Z' + environment_id: env_88640229614813449 + display_name: connected account deleted + data: + authorization_type: OAUTH + connection_id: conn_101644109747323155 + id: ca_101649788113519113 + identifier: Clark + last_used_at: '2025-12-02T06:00:01.374253Z' + provider: GOOGLE_ADS + status: ACTIVE + token_expires_at: '2025-12-02T06:59:57.237447Z' + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/connected_account.magic_link_generated.yaml b/openapi/webhooks/connected_account.magic_link_generated.yaml new file mode 100644 index 000000000..6b54bbc45 --- /dev/null +++ b/openapi/webhooks/connected_account.magic_link_generated.yaml @@ -0,0 +1,25 @@ +post: + summary: Connected Account Magic Link Generated + description: Triggered when a magic link is generated for OAuth flow + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_101652975398683158 + type: connected_account.magic_link_generated + object: ConnectedAccount + occurred_at: '2025-12-02T06:31:34.895815554Z' + environment_id: env_88640229614813448 + data: + authorization_type: OAUTH + connection_id: conn_100510054016352776 + id: ca_100510623602835982 + identifier: Pranesh + provider: SUPABASE + status: PENDING_AUTH + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/connected_account.oauth_succeeded.yaml b/openapi/webhooks/connected_account.oauth_succeeded.yaml new file mode 100644 index 000000000..2796bb029 --- /dev/null +++ b/openapi/webhooks/connected_account.oauth_succeeded.yaml @@ -0,0 +1,26 @@ +post: + summary: Connected Account OAuth Succeeded + description: Triggered when OAuth authentication succeeds + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_101649484227871236 + type: connected_account.oauth_succeeded + object: ConnectedAccount + occurred_at: '2025-12-02T05:56:53.994604757Z' + environment_id: env_88640229614813449 + data: + authorization_type: OAUTH + connection_id: conn_101644109747323155 + id: ca_101649474950005257 + identifier: Bruce + provider: GOOGLE_ADS + status: ACTIVE + token_expires_at: '2025-12-02T06:56:52.976081699Z' + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/connected_account.oauth_tokens_fetched.yaml b/openapi/webhooks/connected_account.oauth_tokens_fetched.yaml new file mode 100644 index 000000000..92b293ac0 --- /dev/null +++ b/openapi/webhooks/connected_account.oauth_tokens_fetched.yaml @@ -0,0 +1,26 @@ +post: + summary: Connected Account OAuth Tokens Fetched + description: Triggered when OAuth tokens are successfully fetched + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_101649795042509316 + type: connected_account.oauth_tokens_fetched + object: ConnectedAccount + occurred_at: '2025-12-02T05:59:59.250126407Z' + environment_id: env_88640229614813449 + data: + authorization_type: OAUTH + connection_id: conn_101644109747323155 + id: ca_101649788113519113 + identifier: Clark + provider: GOOGLE_ADS + status: ACTIVE + token_expires_at: '2025-12-02T06:59:57.237447778Z' + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/connected_account.token_refresh_failed.yaml b/openapi/webhooks/connected_account.token_refresh_failed.yaml new file mode 100644 index 000000000..c23b49918 --- /dev/null +++ b/openapi/webhooks/connected_account.token_refresh_failed.yaml @@ -0,0 +1,26 @@ +post: + summary: Connected Account Token Refresh Failed + description: Triggered when token refresh fails + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_101649795042509316 + type: connected_account.token_refresh_failed + object: ConnectedAccount + occurred_at: '2025-12-02T05:59:59.250126407Z' + environment_id: env_88640229614813445 + data: + authorization_type: OAUTH + connection_id: conn_101644109747323155 + id: ca_101649788113519113 + identifier: Clark + provider: GOOGLE_ADS + status: ACTIVE + token_expires_at: '2025-12-02T06:59:57.237447778Z' + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/connected_account.token_refresh_succeeded.yaml b/openapi/webhooks/connected_account.token_refresh_succeeded.yaml new file mode 100644 index 000000000..c151ad99b --- /dev/null +++ b/openapi/webhooks/connected_account.token_refresh_succeeded.yaml @@ -0,0 +1,27 @@ +post: + summary: Connected Account Token Refresh Succeeded + description: Triggered when token refresh succeeds + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_101651946317808143 + type: connected_account.token_refresh_succeeded + object: ConnectedAccount + occurred_at: '2025-12-02T06:21:21.517480021Z' + environment_id: env_88640229614813449 + data: + authorization_type: OAUTH + connection_id: conn_101644109747323155 + id: ca_101644170698948883 + identifier: Pranesh + last_used_at: '2025-12-02T06:21:21.393723232Z' + provider: GOOGLE_ADS + status: ACTIVE + token_expires_at: '2025-12-02T07:21:20.508197312Z' + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/connected_account.updated.yaml b/openapi/webhooks/connected_account.updated.yaml new file mode 100644 index 000000000..40fa95787 --- /dev/null +++ b/openapi/webhooks/connected_account.updated.yaml @@ -0,0 +1,26 @@ +post: + summary: Connected Account Updated + description: Triggered when a connected account is updated + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_101652975398683158 + type: connected_account.updated + object: ConnectedAccount + occurred_at: '2025-12-02T06:31:34.895815554Z' + environment_id: env_88640229614813449 + display_name: Connected account updated + data: + authorization_type: OAUTH + connection_id: conn_100510054016352776 + id: ca_100510623602835982 + identifier: Pranesh + provider: SUPABASE + status: PENDING_AUTH + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/organization.created.yaml b/openapi/webhooks/organization.created.yaml new file mode 100644 index 000000000..92ae035d1 --- /dev/null +++ b/openapi/webhooks/organization.created.yaml @@ -0,0 +1,34 @@ +post: + summary: Organization Created + description: Triggered when a new organization is created in Scalekit + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_1234567890 + type: organization.created + object: Organization + occurred_at: '2024-01-15T10:30:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_1234567890 + data: + create_time: '2025-12-09T09:25:02.02Z' + display_name: AcmeCorp + external_id: org_external_123 + id: org_1234567890 + metadata: null + region_code: US + update_time: '2025-12-09T09:25:02.025330364Z' + settings: + features: + - enabled: true + name: sso + - enabled: false + name: dir_sync + display_name: Organization Created + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/organization.deleted.yaml b/openapi/webhooks/organization.deleted.yaml new file mode 100644 index 000000000..d5790626b --- /dev/null +++ b/openapi/webhooks/organization.deleted.yaml @@ -0,0 +1,35 @@ +post: + summary: Organization Deleted + description: Triggered when an organization is deleted + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_3456789012 + type: organization.deleted + object: Organization + occurred_at: '2024-01-15T10:40:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_1234567890 + data: + create_time: '2025-12-09T09:25:02.02Z' + deleted_at: '2025-12-09T10:25:45.337417Z' + display_name: AcmeCorp + external_id: org_external_123 + id: org_1234567890 + metadata: null + region_code: US + update_time: '2025-12-09T09:25:02.025330364Z' + settings: + features: + - enabled: true + name: sso + - enabled: false + name: dir_sync + display_name: Organization Deleted + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/organization.directory.group_created.yaml b/openapi/webhooks/organization.directory.group_created.yaml new file mode 100644 index 000000000..3fd5ec356 --- /dev/null +++ b/openapi/webhooks/organization.directory.group_created.yaml @@ -0,0 +1,27 @@ +post: + summary: Directory Group Created + description: Triggered when a new directory group is created + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_38862741515010639 + type: organization.directory.group_created + object: DirectoryGroup + occurred_at: '2024-09-25T02:26:39.036398577Z' + environment_id: env_32080745237316098 + organization_id: org_38609339635728478 + data: + directory_id: dir_38610496391217780 + display_name: Avengers + external_id: null + id: dirgroup_38862741498233423 + organization_id: org_38609339635728478 + raw_attributes: {} + display_name: Directory Group Created + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/organization.directory.group_deleted.yaml b/openapi/webhooks/organization.directory.group_deleted.yaml new file mode 100644 index 000000000..0583516de --- /dev/null +++ b/openapi/webhooks/organization.directory.group_deleted.yaml @@ -0,0 +1,27 @@ +post: + summary: Directory Group Deleted + description: Triggered when a directory group is deleted + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_40650399597723966 + type: organization.directory.group_deleted + object: DirectoryGroup + occurred_at: '2024-10-07T10:25:26.289331747Z' + environment_id: env_12205603854221623 + organization_id: org_39802449573184223 + data: + directory_id: dir_39802485862301855 + display_name: Admins + dp_id: 7c66a173-79c6-4270-ac78-8f35a8121e0a + id: dirgroup_40072007005503806 + organization_id: org_39802449573184223 + raw_attributes: {} + display_name: Directory Group Deleted + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/organization.directory.group_updated.yaml b/openapi/webhooks/organization.directory.group_updated.yaml new file mode 100644 index 000000000..99c312940 --- /dev/null +++ b/openapi/webhooks/organization.directory.group_updated.yaml @@ -0,0 +1,27 @@ +post: + summary: Directory Group Updated + description: Triggered when a directory group is updated + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_38864948910162368 + type: organization.directory.group_updated + object: DirectoryGroup + occurred_at: '2024-09-25T02:48:34.745030921Z' + environment_id: env_32080745237316098 + organization_id: org_38609339635728478 + data: + directory_id: dir_38610496391217780 + display_name: Avengers + external_id: + id: dirgroup_38862741498233423 + organization_id: org_38609339635728478 + raw_attributes: {} + display_name: Directory Group Updated + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/organization.directory.user_created.yaml b/openapi/webhooks/organization.directory.user_created.yaml new file mode 100644 index 000000000..9ccbbf44f --- /dev/null +++ b/openapi/webhooks/organization.directory.user_created.yaml @@ -0,0 +1,51 @@ +post: + summary: Directory User Created + description: Triggered when a new directory user is created + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_53891546994442316 + type: organization.directory.user_created + object: DirectoryUser + occurred_at: '2025-01-06T18:44:25.153954Z' + environment_id: env_53814739859406915 + organization_id: org_53879494091473415 + data: + active: true + cost_center: QAUZJUHSTYCN + custom_attributes: + mobile_phone_number: 1-579-4072 + department: HNXJPGISMIFN + division: MJFUEYJOKICN + dp_id: + email: flavio@runolfsdottir.co.duk + employee_id: AWNEDTILGaIZN + family_name: Jaquelin + given_name: Dayton + groups: + - id: dirgroup_12312312312312 + name: Group Name + id: diruser_53891546960887884 + language: se + locale: LLWLEWESPLDC + name: QDRGUZZDYMFU + nickname: DTUODYKGFPPC + organization: AUIITQVUQGVH + organization_id: org_53879494091473415 + phone_number: 1-579-4072 + preferred_username: kuntala1233a + profile: YMIUQUHKGVAX + raw_attributes: {} + title: FKQBHCWJXZSC + user_type: RBQFJSQEFAEH + zoneinfo: America/Araguaina + roles: + - role_name: billing_admin + display_name: Directory User Created + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/organization.directory.user_deleted.yaml b/openapi/webhooks/organization.directory.user_deleted.yaml new file mode 100644 index 000000000..cc00555eb --- /dev/null +++ b/openapi/webhooks/organization.directory.user_deleted.yaml @@ -0,0 +1,25 @@ +post: + summary: Directory User Deleted + description: Triggered when a directory user is deleted + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_53891546994442318 + type: organization.directory.user_deleted + object: DirectoryUser + occurred_at: '2025-01-06T18:44:25.153954Z' + environment_id: env_53814739859406915 + organization_id: org_53879494091473415 + data: + id: diruser_12312312312312 + organization_id: org_12312312312312 + dp_id: + email: john.doe@example.com + display_name: Directory User Deleted + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/organization.directory.user_updated.yaml b/openapi/webhooks/organization.directory.user_updated.yaml new file mode 100644 index 000000000..b6fb34ce8 --- /dev/null +++ b/openapi/webhooks/organization.directory.user_updated.yaml @@ -0,0 +1,46 @@ +post: + summary: Directory User Updated + description: Triggered when a directory user is updated + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_53891546994442317 + type: organization.directory.user_updated + object: DirectoryUser + occurred_at: '2025-01-06T18:44:25.153954Z' + environment_id: env_53814739859406915 + organization_id: org_53879494091473415 + data: + id: diruser_12312312312312 + organization_id: org_53879494091473415 + dp_id: + preferred_username: + email: john.doe@example.com + active: true + name: John Doe + roles: + - role_name: billing_admin + groups: + - id: dirgroup_12312312312312 + name: Group Name + given_name: John + family_name: Doe + nickname: Jhonny boy + picture: https://image.com/profile.jpg + phone_number: '1234567892' + address: + postal_code: '64112' + state: Missouri + formatted: 123, Oxford Lane, Kansas City, Missouri, 64112 + custom_attributes: + attribute1: value1 + attribute2: value2 + raw_attributes: {} + display_name: Directory User Updated + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/organization.directory_disabled.yaml b/openapi/webhooks/organization.directory_disabled.yaml new file mode 100644 index 000000000..f3f61d2e2 --- /dev/null +++ b/openapi/webhooks/organization.directory_disabled.yaml @@ -0,0 +1,27 @@ +post: + summary: Directory Disabled + description: Triggered when a directory sync is disabled + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_53891640779079756 + type: organization.directory_disabled + object: Directory + occurred_at: '2025-01-06T18:45:21.057814Z' + environment_id: env_53814739859406915 + organization_id: org_53879494091473415 + data: + directory_type: SCIM + enabled: false + id: dir_53879621145330183 + organization_id: org_53879494091473415 + provider: OKTA + updated_at: '2025-01-06T18:45:21.04978184Z' + display_name: Directory Disabled + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/organization.directory_enabled.yaml b/openapi/webhooks/organization.directory_enabled.yaml new file mode 100644 index 000000000..ce766f2db --- /dev/null +++ b/openapi/webhooks/organization.directory_enabled.yaml @@ -0,0 +1,27 @@ +post: + summary: Directory Enabled + description: Triggered when a directory sync is enabled + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_55136848686613000 + type: organization.directory_enabled + object: Directory + occurred_at: '2025-01-15T08:55:22.802860294Z' + environment_id: env_27758032200925221 + organization_id: org_55135410258444802 + data: + directory_type: SCIM + enabled: true + id: dir_55135622825771522 + organization_id: org_55135410258444802 + provider: OKTA + updated_at: '2025-01-15T08:55:22.792993454Z' + display_name: Directory Enabled + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/organization.sso_created.yaml b/openapi/webhooks/organization.sso_created.yaml new file mode 100644 index 000000000..2439ab3b9 --- /dev/null +++ b/openapi/webhooks/organization.sso_created.yaml @@ -0,0 +1,25 @@ +post: + summary: SSO Connection Created + description: Triggered when a new SSO connection is created for an organization + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_94567862441607493 + type: organization.sso_created + object: Connection + environment_id: env_74418471961625391 + occurred_at: '2025-10-14T09:27:18.488720586Z' + organization_id: org_83544995172188677 + data: + id: conn_94567862424830277 + organization_id: org_83544995172188677 + connection_type: OIDC + provider: OKTA + display_name: SSO Connection Created + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/organization.sso_deleted.yaml b/openapi/webhooks/organization.sso_deleted.yaml new file mode 100644 index 000000000..5dd9aaa3b --- /dev/null +++ b/openapi/webhooks/organization.sso_deleted.yaml @@ -0,0 +1,25 @@ +post: + summary: SSO Connection Deleted + description: Triggered when an SSO connection is deleted for an organization + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_94557997639926040 + type: organization.sso_deleted + object: Connection + environment_id: env_74418471961625391 + occurred_at: '2025-10-14T07:49:18.604546332Z' + organization_id: org_83544995172188677 + data: + id: conn_83545002856153607 + organization_id: org_83544995172188677 + connection_type: OIDC + provider: OKTA + display_name: SSO Connection Deleted + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/organization.sso_disabled.yaml b/openapi/webhooks/organization.sso_disabled.yaml new file mode 100644 index 000000000..414df02f0 --- /dev/null +++ b/openapi/webhooks/organization.sso_disabled.yaml @@ -0,0 +1,27 @@ +post: + summary: SSO Connection Disabled + description: Triggered when an SSO connection is disabled for an organization + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_94557976165089560 + type: organization.sso_disabled + object: Connection + environment_id: env_74418471961625391 + occurred_at: '2025-10-14T07:49:05.809554456Z' + organization_id: org_83544995172188677 + data: + id: conn_83545002856153607 + organization_id: org_83544995172188677 + connection_type: OIDC + provider: OKTA + enabled: false + status: COMPLETED + display_name: SSO Connection Disabled + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/organization.sso_enabled.yaml b/openapi/webhooks/organization.sso_enabled.yaml new file mode 100644 index 000000000..bdeec8119 --- /dev/null +++ b/openapi/webhooks/organization.sso_enabled.yaml @@ -0,0 +1,27 @@ +post: + summary: SSO Connection Enabled + description: Triggered when an SSO connection is enabled for an organization + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_94568078213382471 + type: organization.sso_enabled + object: Connection + environment_id: env_74418471961625391 + occurred_at: '2025-10-14T09:29:27.098914861Z' + organization_id: org_83544995172188677 + data: + id: conn_94567862424830277 + organization_id: org_83544995172188677 + connection_type: OIDC + provider: OKTA + enabled: true + status: COMPLETED + display_name: SSO Connection Enabled + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/organization.updated.yaml b/openapi/webhooks/organization.updated.yaml new file mode 100644 index 000000000..fcce44391 --- /dev/null +++ b/openapi/webhooks/organization.updated.yaml @@ -0,0 +1,34 @@ +post: + summary: Organization Updated + description: Triggered when an organization is updated + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_2345678901 + type: organization.updated + object: Organization + occurred_at: '2024-01-15T10:35:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_1234567890 + data: + create_time: '2025-12-09T09:25:02.02Z' + display_name: AcmeCorp + external_id: org_external_123 + id: org_1234567890 + metadata: null + region_code: US + update_time: '2025-12-09T09:25:02.025330364Z' + settings: + features: + - enabled: true + name: sso + - enabled: false + name: dir_sync + display_name: Organization Updated + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/permission.created.yaml b/openapi/webhooks/permission.created.yaml new file mode 100644 index 000000000..ad0fdbb62 --- /dev/null +++ b/openapi/webhooks/permission.created.yaml @@ -0,0 +1,23 @@ +post: + summary: Permission Created + description: Triggered when a new permission is created + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_1234567890 + type: permission.created + object: Permission + occurred_at: '2024-01-15T10:30:00.123456789Z' + environment_id: env_1234567890 + data: + description: Permission to manage data + id: perm_1234567890 + name: data:manage + display_name: Permission Created + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/permission.deleted.yaml b/openapi/webhooks/permission.deleted.yaml new file mode 100644 index 000000000..fed7ca704 --- /dev/null +++ b/openapi/webhooks/permission.deleted.yaml @@ -0,0 +1,23 @@ +post: + summary: Permission Deleted + description: Triggered when a permission is deleted + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_3456789012 + type: permission.deleted + object: Permission + occurred_at: '2024-01-15T10:40:00.123456789Z' + environment_id: env_1234567890 + data: + description: Updated permission to manage all data + id: perm_1234567890 + name: data:manage + display_name: Permission Deleted + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/permission.updated.yaml b/openapi/webhooks/permission.updated.yaml new file mode 100644 index 000000000..5c67972b0 --- /dev/null +++ b/openapi/webhooks/permission.updated.yaml @@ -0,0 +1,23 @@ +post: + summary: Permission Updated + description: Triggered when a permission is updated + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_2345678901 + type: permission.updated + object: Permission + occurred_at: '2024-01-15T10:35:00.123456789Z' + environment_id: env_1234567890 + data: + description: Updated permission to manage all data + id: perm_1234567890 + name: data:manage + display_name: Permission Updated + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/role.created.yaml b/openapi/webhooks/role.created.yaml new file mode 100644 index 000000000..e84dac0d0 --- /dev/null +++ b/openapi/webhooks/role.created.yaml @@ -0,0 +1,25 @@ +post: + summary: Role Created + description: Triggered when a new role is created + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_1234567890 + type: role.created + object: Role + occurred_at: '2024-01-15T10:30:00.123456789Z' + environment_id: env_1234567890 + data: + description: Viewer role with read-only access + display_name: Viewer + extends: member + id: role_1234567890 + name: viewer + display_name: Role Created + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/role.deleted.yaml b/openapi/webhooks/role.deleted.yaml new file mode 100644 index 000000000..cfd4e324a --- /dev/null +++ b/openapi/webhooks/role.deleted.yaml @@ -0,0 +1,25 @@ +post: + summary: Role Deleted + description: Triggered when a role is deleted + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_3456789012 + type: role.deleted + object: Role + occurred_at: '2024-01-15T10:40:00.123456789Z' + environment_id: env_1234567890 + data: + description: Updated viewer role with limited permissions + display_name: Viewer + extends: member + id: role_1234567890 + name: viewer + display_name: Role Deleted + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/role.updated.yaml b/openapi/webhooks/role.updated.yaml new file mode 100644 index 000000000..0baead23f --- /dev/null +++ b/openapi/webhooks/role.updated.yaml @@ -0,0 +1,25 @@ +post: + summary: Role Updated + description: Triggered when a role is updated + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_2345678901 + type: role.updated + object: Role + occurred_at: '2024-01-15T10:35:00.123456789Z' + environment_id: env_1234567890 + data: + description: Updated viewer role with limited permissions + display_name: Viewer + extends: member + id: role_1234567890 + name: viewer + display_name: Role Updated + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/user.login.yaml b/openapi/webhooks/user.login.yaml new file mode 100644 index 000000000..91ae8344b --- /dev/null +++ b/openapi/webhooks/user.login.yaml @@ -0,0 +1,84 @@ +post: + summary: User Login + description: Triggered when a user logs in and a session is created + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_102701193859432713 + type: user.login + object: User + occurred_at: '2025-12-09T12:04:41.781873312Z' + environment_id: env_96736846679245078 + organization_id: org_102701193188409609 + data: + user: + create_time: '2025-12-09T12:04:41.39Z' + email: john.doe@acmecorp.com + external_id: ext_123456789 + id: usr_123456789 + last_login_time: '2025-12-09T12:04:41.48Z' + metadata: {} + update_time: '2025-12-09T12:04:41.391988Z' + user_profile: + custom_attributes: null + email_verified: true + external_identities: + - connection_id: conn_97896332307464201 + connection_provider: GOOGLE + connection_type: OAUTH + connection_user_id: '105055379523565727691' + created_time: '2025-12-09T12:04:41.47Z' + is_social: true + last_login_time: '2025-12-09T12:04:41.469311Z' + last_synced_time: '2025-12-09T12:04:41.469311Z' + family_name: Doe + gender: '' + given_name: John + groups: null + id: usp_102701193205186825 + locale: '' + metadata: {} + name: John Doe + phone_number: '' + phone_number_verified: false + picture: https://lh3.googleusercontent.com/a/abcdef + preferred_username: '' + user_session: + absolute_expires_at: '2026-01-08T12:04:41.737394Z' + authenticated_organizations: + - org_102701193188409609 + created_at: '2025-12-09T12:04:41.48Z' + expired_at: null + idle_expires_at: '2025-12-16T12:04:41.737395Z' + last_active_at: '2025-12-09T12:04:41.747206Z' + logout_at: null + organization_id: org_102701193188409609 + session_id: ses_102701193356116233 + status: ACTIVE + updated_at: '2025-12-09T12:04:41.748512Z' + user_id: usr_102701193205121289 + device: + browser: Chrome + browser_version: 142.0.0.0 + device_type: Desktop + ip: 152.59.144.211 + location: + city: Patna + latitude: '25.594095' + longitude: '85.137564' + region: IN + region_subdivision: INBR + os: macOS + os_version: 10.15.7 + user_agent: >- + Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) + AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 + Safari/537.36 + display_name: User Login + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/user.logout.yaml b/openapi/webhooks/user.logout.yaml new file mode 100644 index 000000000..bf3d7178a --- /dev/null +++ b/openapi/webhooks/user.logout.yaml @@ -0,0 +1,84 @@ +post: + summary: User Logout + description: Triggered when a user's session is terminated + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_102708230123160586 + type: user.logout + object: User + occurred_at: '2025-12-09T13:14:35.722070822Z' + environment_id: env_96736846679245078 + organization_id: org_102701193188409609 + data: + user: + create_time: '2025-12-09T12:04:41.39Z' + email: john.doe@acmecorp.com + external_id: ext_123456789 + id: usr_123456789 + last_login_time: '2025-12-09T12:04:41.48Z' + metadata: {} + update_time: '2025-12-09T12:04:41.391988Z' + user_profile: + custom_attributes: null + email_verified: true + external_identities: + - connection_id: conn_97896332307464201 + connection_provider: GOOGLE + connection_type: OAUTH + connection_user_id: '105055379523565727691' + created_time: '2025-12-09T12:04:41.47Z' + is_social: true + last_login_time: '2025-12-09T12:04:41.469311Z' + last_synced_time: '2025-12-09T12:04:41.469311Z' + family_name: Doe + gender: '' + given_name: John + groups: null + id: usp_102701193205186825 + locale: '' + metadata: {} + name: John Doe + phone_number: '' + phone_number_verified: false + picture: https://lh3.googleusercontent.com/a/abcdef + preferred_username: '' + user_session: + absolute_expires_at: '2026-01-08T12:04:41.737394Z' + authenticated_organizations: + - org_102701193188409609 + created_at: '2025-12-09T12:04:41.48Z' + expired_at: null + idle_expires_at: '2025-12-16T12:04:41.737395Z' + last_active_at: '2025-12-09T12:04:41.747206Z' + logout_at: null + organization_id: org_102701193188409609 + session_id: ses_102701193356116233 + status: ACTIVE + updated_at: '2025-12-09T12:04:41.748512Z' + user_id: usr_102701193205121289 + device: + browser: Chrome + browser_version: 142.0.0.0 + device_type: Desktop + ip: 152.59.144.211 + location: + city: Patna + latitude: '25.594095' + longitude: '85.137564' + region: IN + region_subdivision: INBR + os: macOS + os_version: 10.15.7 + user_agent: >- + Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) + AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 + Safari/537.36 + display_name: User Logout + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/user.organization_invitation.yaml b/openapi/webhooks/user.organization_invitation.yaml new file mode 100644 index 000000000..acb879d6d --- /dev/null +++ b/openapi/webhooks/user.organization_invitation.yaml @@ -0,0 +1,66 @@ +post: + summary: User Organization Invitation + description: Triggered when a user is invited to join an organization + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_4567890123 + type: user.organization_invitation + object: OrgMembership + occurred_at: '2024-01-15T11:00:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_102690563312124938 + data: + organization: + id: org_102690563312124938 + create_time: '2025-12-09T10:19:05.48Z' + display_name: Acme Corp + external_id: org_external_123 + metadata: null + region_code: US + update_time: '2025-12-09T12:04:41.386974738Z' + settings: + features: + - enabled: true + name: sso + - enabled: true + name: dir_sync + user: + create_time: '2025-12-09T12:04:41.39Z' + email: john.doe@acmecorp.com + external_id: ext_123456789 + id: usr_123456789 + metadata: {} + update_time: '2025-12-09T12:04:41.391988Z' + user_profile: + custom_attributes: null + email_verified: true + external_identities: + - connection_id: conn_97896332307464201 + connection_provider: GOOGLE + connection_type: OAUTH + connection_user_id: '105055379523565727691' + created_time: '2025-12-09T12:04:41.47Z' + is_social: true + last_login_time: '2025-12-09T12:04:41.469311Z' + last_synced_time: '2025-12-09T12:04:41.469311Z' + family_name: Doe + gender: '' + given_name: John + groups: null + id: usp_102701193205186825 + locale: '' + metadata: {} + name: John Doe + phone_number: '' + phone_number_verified: false + picture: https://lh3.googleusercontent.com/a/abcdef + preferred_username: '' + display_name: User Organization Invitation + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/user.organization_membership_created.yaml b/openapi/webhooks/user.organization_membership_created.yaml new file mode 100644 index 000000000..26713801a --- /dev/null +++ b/openapi/webhooks/user.organization_membership_created.yaml @@ -0,0 +1,66 @@ +post: + summary: User Organization Membership Created + description: Triggered when a user joins an organization + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_5678901234 + type: user.organization_membership_created + object: OrgMembership + occurred_at: '2024-01-15T11:05:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_102690563312124938 + data: + organization: + id: org_102690563312124938 + create_time: '2025-12-09T10:19:05.48Z' + display_name: Acme Corp + external_id: org_external_123 + metadata: null + region_code: US + update_time: '2025-12-09T12:04:41.386974738Z' + settings: + features: + - enabled: true + name: sso + - enabled: true + name: dir_sync + user: + create_time: '2025-12-09T12:04:41.39Z' + email: john.doe@acmecorp.com + external_id: ext_123456789 + id: usr_123456789 + metadata: {} + update_time: '2025-12-09T12:04:41.391988Z' + user_profile: + custom_attributes: null + email_verified: true + external_identities: + - connection_id: conn_97896332307464201 + connection_provider: GOOGLE + connection_type: OAUTH + connection_user_id: '105055379523565727691' + created_time: '2025-12-09T12:04:41.47Z' + is_social: true + last_login_time: '2025-12-09T12:04:41.469311Z' + last_synced_time: '2025-12-09T12:04:41.469311Z' + family_name: Doe + gender: '' + given_name: John + groups: null + id: usp_102701193205186825 + locale: '' + metadata: {} + name: John Doe + phone_number: '' + phone_number_verified: false + picture: https://lh3.googleusercontent.com/a/abcdef + preferred_username: '' + display_name: User Organization Membership Created + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/user.organization_membership_deleted.yaml b/openapi/webhooks/user.organization_membership_deleted.yaml new file mode 100644 index 000000000..2bbce2ff1 --- /dev/null +++ b/openapi/webhooks/user.organization_membership_deleted.yaml @@ -0,0 +1,66 @@ +post: + summary: User Organization Membership Deleted + description: Triggered when a user's membership in an organization is removed or deleted + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_9012345678 + type: user.organization_membership_deleted + object: OrgMembership + occurred_at: '2024-01-15T11:10:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_102690563312124938 + data: + organization: + id: org_102690563312124938 + create_time: '2025-12-09T10:19:05.48Z' + display_name: Acme Corp + external_id: org_external_123 + metadata: null + region_code: US + update_time: '2025-12-09T12:04:41.386974738Z' + settings: + features: + - enabled: true + name: sso + - enabled: true + name: dir_sync + user: + create_time: '2025-12-09T12:04:41.39Z' + email: john.doe@acmecorp.com + external_id: ext_123456789 + id: usr_123456789 + metadata: {} + update_time: '2025-12-09T12:04:41.391988Z' + user_profile: + custom_attributes: null + email_verified: true + external_identities: + - connection_id: conn_97896332307464201 + connection_provider: GOOGLE + connection_type: OAUTH + connection_user_id: '105055379523565727691' + created_time: '2025-12-09T12:04:41.47Z' + is_social: true + last_login_time: '2025-12-09T12:04:41.469311Z' + last_synced_time: '2025-12-09T12:04:41.469311Z' + raw_attributes: '{}' + updated_time: '2025-12-09T12:04:41.473087Z' + family_name: Doe + gender: '' + given_name: John + locale: '' + metadata: {} + name: John Doe + phone_number: '' + phone_number_verified: false + picture: https://lh3.googleusercontent.com/a/abcdef + preferred_username: '' + display_name: User Organization Membership Deleted + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/user.organization_membership_updated.yaml b/openapi/webhooks/user.organization_membership_updated.yaml new file mode 100644 index 000000000..a67f23100 --- /dev/null +++ b/openapi/webhooks/user.organization_membership_updated.yaml @@ -0,0 +1,68 @@ +post: + summary: User Organization Membership Updated + description: >- + Triggered when a user's organization membership is updated, e.g., change of + user's role in an organization + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_6789012345 + type: user.organization_membership_updated + object: OrgMembership + occurred_at: '2024-01-15T11:10:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_102690563312124938 + data: + organization: + id: org_102690563312124938 + create_time: '2025-12-09T10:19:05.48Z' + display_name: Acme Corp + external_id: org_external_123 + metadata: null + region_code: US + update_time: '2025-12-09T12:04:41.386974738Z' + settings: + features: + - enabled: true + name: sso + - enabled: true + name: dir_sync + user: + create_time: '2025-12-09T12:04:41.39Z' + email: john.doe@acmecorp.com + external_id: ext_123456789 + id: usr_123456789 + metadata: {} + update_time: '2025-12-09T12:04:41.391988Z' + user_profile: + custom_attributes: null + email_verified: true + external_identities: + - connection_id: conn_97896332307464201 + connection_provider: GOOGLE + connection_type: OAUTH + connection_user_id: '105055379523565727691' + created_time: '2025-12-09T12:04:41.47Z' + is_social: true + last_login_time: '2025-12-09T12:04:41.469311Z' + last_synced_time: '2025-12-09T12:04:41.469311Z' + raw_attributes: '{}' + updated_time: '2025-12-09T12:04:41.473087Z' + family_name: Doe + gender: '' + given_name: John + locale: '' + metadata: {} + name: John Doe + phone_number: '' + phone_number_verified: false + picture: https://lh3.googleusercontent.com/a/abcdef + preferred_username: '' + display_name: User Organization Membership Updated + responses: + '200': + description: Webhook received successfully diff --git a/openapi/webhooks/user.signup.yaml b/openapi/webhooks/user.signup.yaml new file mode 100644 index 000000000..373b7ba96 --- /dev/null +++ b/openapi/webhooks/user.signup.yaml @@ -0,0 +1,58 @@ +post: + summary: User Signup + description: Triggered when a user signs up to create a new organization + requestBody: + content: + application/json: + schema: + $ref: ../components/schemas/ScalekitEvent.yaml + example: + spec_version: '1' + id: evt_1234567890 + type: user.signup + object: OrgMembership + occurred_at: '2024-01-15T10:30:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_102690563312124938 + data: + organization: + id: org_102690563312124938 + create_time: '2025-12-09T10:19:05.48Z' + display_name: '' + external_id: null + metadata: null + region_code: US + update_time: '2025-12-09T12:04:41.386974738Z' + settings: + features: + - enabled: true + name: sso + - enabled: true + name: dir_sync + user: + create_time: '2025-12-09T12:04:41.39Z' + email: amit.ash1996@gmail.com + external_id: '' + id: usr_102701193205121289 + metadata: {} + update_time: '2025-12-09T12:04:41.391988278Z' + user_profile: + custom_attributes: null + email_verified: true + external_identities: null + family_name: doe + gender: '' + given_name: John + groups: null + id: usp_102701193205186825 + locale: '' + metadata: {} + name: John Doe + phone_number: '' + phone_number_verified: false + picture: https://lh3.googleusercontent.com/a/abcdef + preferred_username: '' + display_name: User Signup + responses: + '200': + description: Webhook received successfully diff --git a/package.json b/package.json index b6540c2b1..cf274d005 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,8 @@ "format:check": "prettier --check '**/*.{md,mdx,js,ts,astro,css,vue}'", "format": "prettier --write '**/*.{md,mdx,js,ts,astro,css,vue}'", "reorder-swagger": "node scripts/reorder-swagger.js public/api/scalekit.scalar.json", + "split-api": "redocly split public/api/scalekit.scalar.yaml --outDir=openapi && redocly bundle agentkit --remove-unused-components && redocly bundle saaskit --remove-unused-components", + "split-api:lint": "redocly lint openapi/agentkit.yaml && redocly lint openapi/saaskit.yaml", "sync-agent-connectors": "node scripts/sync-agent-connectors.js" }, "dependencies": { @@ -67,6 +69,7 @@ }, "devDependencies": { "@astrojs/check": "^0.9.8", + "@redocly/cli": "^2.31.2", "@scalar/openapi-to-markdown": "^0.5.6", "@types/react": "^19.2.14", "@types/react-dom": "^19.2.3", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index fa87097b5..589dad181 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -154,6 +154,9 @@ importers: '@astrojs/check': specifier: ^0.9.8 version: 0.9.8(prettier-plugin-astro@0.14.1)(prettier@3.8.3)(typescript@6.0.3) + '@redocly/cli': + specifier: ^2.31.2 + version: 2.31.2(@opentelemetry/api@1.9.1)(core-js@3.49.0) '@scalar/openapi-to-markdown': specifier: ^0.5.6 version: 0.5.6(typescript@6.0.3) @@ -617,6 +620,12 @@ packages: '@emnapi/runtime@1.10.0': resolution: {integrity: sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==} + '@emotion/is-prop-valid@1.4.0': + resolution: {integrity: sha512-QgD4fyscGcbbKwJmqNvUMSE02OsHUa+lAWKdEUIJKgqe5IwRSKd7+KhibEWdaKwgjLj0DRSHA9biAIqGBk05lw==} + + '@emotion/memoize@0.9.0': + resolution: {integrity: sha512-30FAj7/EoJ5mwVPOWhAyCX+FPfMDrVecJAM+Iw9NRoSl4BBAQeqj4cApHHUXOVvIPgLVDsCFoz/hGD+5QQD1GQ==} + '@envelop/instrumentation@1.0.0': resolution: {integrity: sha512-cxgkB66RQB95H3X27jlnxCRNTmPuSTgmBAq6/4n2Dtv4hsk4yz8FadA1ggmd0uZzvKqWD6CR+WFgTjhDqg7eyw==} engines: {node: '>=18.0.0'} @@ -936,6 +945,9 @@ packages: cpu: [x64] os: [win32] + '@exodus/schemasafe@1.3.0': + resolution: {integrity: sha512-5Aap/GaRupgNx/feGBwLLTVv8OQFfv3pq2lPRzPg9R+IOBnDgghTGW7l7EuVXOvg5cc/xSAlRW8rBrjIC3Nvqw==} + '@expressive-code/core@0.41.7': resolution: {integrity: sha512-ck92uZYZ9Wba2zxkiZLsZGi9N54pMSAVdrI9uW3Oo9AtLglD5RmrdTwbYPCT2S/jC36JGB2i+pnQtBm/Ib2+dg==} @@ -954,6 +966,10 @@ packages: '@expressive-code/plugin-text-markers@0.41.7': resolution: {integrity: sha512-Ewpwuc5t6eFdZmWlFyeuy3e1PTQC0jFvw2Q+2bpcWXbOZhPLsT7+h8lsSIJxb5mS7wZko7cKyQ2RLYDyK6Fpmw==} + '@faker-js/faker@7.6.0': + resolution: {integrity: sha512-XK6BTq1NDMo9Xqw/YkYyGjSsg44fbNwYRx7QK2CuoQgyy+f1rrTDHoExVM5PsyXCtfl2vs2vVJ0MN0yN6LppRw==} + engines: {node: '>=14.0.0', npm: '>=6.0.0'} + '@fastify/accept-negotiator@2.0.1': resolution: {integrity: sha512-/c/TW2bO/v9JeEgoD/g1G5GxGeCF1Hafdf79WPmUlgYiBXummY0oX3VVq4yFkKKVBKDNlaDUYoab7g38RpPqCQ==} @@ -1547,6 +1563,10 @@ packages: engines: {node: '>=18.14.0'} hasBin: true + '@noble/hashes@1.8.0': + resolution: {integrity: sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==} + engines: {node: ^14.21.3 || >=16} + '@nodable/entities@1.1.0': resolution: {integrity: sha512-bidpxmTBP0pOsxULw6XlxzQpTgrAGLDHGBK/JuWhPDL6ZV0GZ/PmN9CA9do6e+A9lYI6qx6ikJUtJYRxup141g==} @@ -1704,6 +1724,10 @@ packages: resolution: {integrity: sha512-9B9RU0H7Ya1Dx/Rkyc4stuBZSGVQF27WigitInx2QQoj6KUpEFYPKoWjdFTunJYxmXmh17HeBvbMa1EhGyPmqQ==} engines: {node: '>=8.0.0'} + '@opentelemetry/api-logs@0.214.0': + resolution: {integrity: sha512-40lSJeqYO8Uz2Yj7u94/SJWE/wONa7rmMKjI1ZcIjgf3MHNHv1OZUCrCETGuaRF62d5pQD1wKIW+L4lmSMTzZA==} + engines: {node: '>=8.0.0'} + '@opentelemetry/api@1.8.0': resolution: {integrity: sha512-I/s6F7yKUDdtMsoBWXJe8Qz40Tui5vsuKCWJEWVL+5q9sSWRzzx6v2KeNsOBEwd94j0eWkpWCH4yB6rZg9Mf0w==} engines: {node: '>=8.0.0'} @@ -1722,18 +1746,48 @@ packages: peerDependencies: '@opentelemetry/api': '>=1.0.0 <1.10.0' + '@opentelemetry/context-async-hooks@2.6.1': + resolution: {integrity: sha512-XHzhwRNkBpeP8Fs/qjGrAf9r9PRv67wkJQ/7ZPaBQQ68DYlTBBx5MF9LvPx7mhuXcDessKK2b+DcxqwpgkcivQ==} + engines: {node: ^18.19.0 || >=20.6.0} + peerDependencies: + '@opentelemetry/api': '>=1.0.0 <1.10.0' + '@opentelemetry/core@1.30.1': resolution: {integrity: sha512-OOCM2C/QIURhJMuKaekP3TRBxBKxG/TWWA0TL2J6nXUtDnuCtccy49LUJF8xPFXMX+0LMcxFpCo8M9cGY1W6rQ==} engines: {node: '>=14'} peerDependencies: '@opentelemetry/api': '>=1.0.0 <1.10.0' + '@opentelemetry/core@2.6.1': + resolution: {integrity: sha512-8xHSGWpJP9wBxgBpnqGL0R3PbdWQndL1Qp50qrg71+B28zK5OQmUgcDKLJgzyAAV38t4tOyLMGDD60LneR5W8g==} + engines: {node: ^18.19.0 || >=20.6.0} + peerDependencies: + '@opentelemetry/api': '>=1.0.0 <1.10.0' + + '@opentelemetry/exporter-trace-otlp-http@0.214.0': + resolution: {integrity: sha512-kIN8nTBMgV2hXzV/a20BCFilPZdAIMYYJGSgfMMRm/Xa+07y5hRDS2Vm12A/z8Cdu3Sq++ZvJfElokX2rkgGgw==} + engines: {node: ^18.19.0 || >=20.6.0} + peerDependencies: + '@opentelemetry/api': ^1.3.0 + '@opentelemetry/instrumentation@0.203.0': resolution: {integrity: sha512-ke1qyM+3AK2zPuBPb6Hk/GCsc5ewbLvPNkEuELx/JmANeEp6ZjnZ+wypPAJSucTw0wvCGrUaibDSdcrGFoWxKQ==} engines: {node: ^18.19.0 || >=20.6.0} peerDependencies: '@opentelemetry/api': ^1.3.0 + '@opentelemetry/otlp-exporter-base@0.214.0': + resolution: {integrity: sha512-u1Gdv0/E9wP+apqWf7Wv2npXmgJtxsW2XL0TEv9FZloTZRuMBKmu8cYVXwS4Hm3q/f/3FuCnPTgiwYvIqRSpRg==} + engines: {node: ^18.19.0 || >=20.6.0} + peerDependencies: + '@opentelemetry/api': ^1.3.0 + + '@opentelemetry/otlp-transformer@0.214.0': + resolution: {integrity: sha512-DSaYcuBRh6uozfsWN3R8HsN0yDhCuWP7tOFdkUOVaWD1KVJg8m4qiLUsg/tNhTLS9HUYUcwNpwL2eroLtsZZ/w==} + engines: {node: ^18.19.0 || >=20.6.0} + peerDependencies: + '@opentelemetry/api': ^1.3.0 + '@opentelemetry/propagator-b3@1.30.1': resolution: {integrity: sha512-oATwWWDIJzybAZ4pO76ATN5N6FFbOA1otibAVlS8v90B4S1wClnhRUk7K+2CHAwN1JKYuj4jh/lpCEG5BAqFuQ==} engines: {node: '>=14'} @@ -1752,22 +1806,56 @@ packages: peerDependencies: '@opentelemetry/api': '>=1.0.0 <1.10.0' + '@opentelemetry/resources@2.6.1': + resolution: {integrity: sha512-lID/vxSuKWXM55XhAKNoYXu9Cutoq5hFdkbTdI/zDKQktXzcWBVhNsOkiZFTMU9UtEWuGRNe0HUgmsFldIdxVA==} + engines: {node: ^18.19.0 || >=20.6.0} + peerDependencies: + '@opentelemetry/api': '>=1.3.0 <1.10.0' + + '@opentelemetry/sdk-logs@0.214.0': + resolution: {integrity: sha512-zf6acnScjhsaBUU22zXZ/sLWim1dfhUAbGXdMmHmNG3LfBnQ3DKsOCITb2IZwoUsNNMTogqFKBnlIPPftUgGwA==} + engines: {node: ^18.19.0 || >=20.6.0} + peerDependencies: + '@opentelemetry/api': '>=1.4.0 <1.10.0' + + '@opentelemetry/sdk-metrics@2.6.1': + resolution: {integrity: sha512-9t9hJHX15meBy2NmTJxL+NJfXmnausR2xUDvE19XQce0Qi/GBtDGamU8nS1RMbdgDmhgpm3VaOu2+fiS/SfTpQ==} + engines: {node: ^18.19.0 || >=20.6.0} + peerDependencies: + '@opentelemetry/api': '>=1.9.0 <1.10.0' + '@opentelemetry/sdk-trace-base@1.30.1': resolution: {integrity: sha512-jVPgBbH1gCy2Lb7X0AVQ8XAfgg0pJ4nvl8/IiQA6nxOsPvS+0zMJaFSs2ltXe0J6C8dqjcnpyqINDJmU30+uOg==} engines: {node: '>=14'} peerDependencies: '@opentelemetry/api': '>=1.0.0 <1.10.0' + '@opentelemetry/sdk-trace-base@2.6.1': + resolution: {integrity: sha512-r86ut4T1e8vNwB35CqCcKd45yzqH6/6Wzvpk2/cZB8PsPLlZFTvrh8yfOS3CYZYcUmAx4hHTZJ8AO8Dj8nrdhw==} + engines: {node: ^18.19.0 || >=20.6.0} + peerDependencies: + '@opentelemetry/api': '>=1.3.0 <1.10.0' + '@opentelemetry/sdk-trace-node@1.30.1': resolution: {integrity: sha512-cBjYOINt1JxXdpw1e5MlHmFRc5fgj4GW/86vsKFxJCJ8AL4PdVtYH41gWwl4qd4uQjqEL1oJVrXkSy5cnduAnQ==} engines: {node: '>=14'} peerDependencies: '@opentelemetry/api': '>=1.0.0 <1.10.0' + '@opentelemetry/sdk-trace-node@2.6.1': + resolution: {integrity: sha512-Hh2i4FwHWRFhnO2Q/p6svMxy8MPsNCG0uuzUY3glqm0rwM0nQvbTO1dXSp9OqQoTKXcQzaz9q1f65fsurmOhNw==} + engines: {node: ^18.19.0 || >=20.6.0} + peerDependencies: + '@opentelemetry/api': '>=1.0.0 <1.10.0' + '@opentelemetry/semantic-conventions@1.28.0': resolution: {integrity: sha512-lp4qAiMTD4sNWW4DbKLBkfiMZ4jbAboJIGOQr5DvciMRI494OapieI9qiODpOt0XBr1LjIDy1xAGAnVs5supTA==} engines: {node: '>=14'} + '@opentelemetry/semantic-conventions@1.40.0': + resolution: {integrity: sha512-cifvXDhcqMwwTlTK04GBNeIe7yyo28Mfby85QXFe1Yk8nmi36Ab/5UQwptOx84SsoGNRg+EVSjwzfSZMy6pmlw==} + engines: {node: '>=14'} + '@oslojs/encoding@1.1.0': resolution: {integrity: sha512-70wQhgYmndg4GCPxPPxPGevRKqTIJ2Nh4OkiMWmDAVYsTQ+Ta7Sq+rPevXyXGdzr30/qZBnyOalCszoMxlyldQ==} @@ -1932,9 +2020,71 @@ packages: '@polka/url@1.0.0-next.29': resolution: {integrity: sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww==} + '@protobufjs/aspromise@1.1.2': + resolution: {integrity: sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==} + + '@protobufjs/base64@1.1.2': + resolution: {integrity: sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==} + + '@protobufjs/codegen@2.0.5': + resolution: {integrity: sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==} + + '@protobufjs/eventemitter@1.1.0': + resolution: {integrity: sha512-j9ednRT81vYJ9OfVuXG6ERSTdEL1xVsNgqpkxMsbIabzSo3goCjDIveeGv5d03om39ML71RdmrGNjG5SReBP/Q==} + + '@protobufjs/fetch@1.1.1': + resolution: {integrity: sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==} + + '@protobufjs/float@1.0.2': + resolution: {integrity: sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==} + + '@protobufjs/inquire@1.1.2': + resolution: {integrity: sha512-pa0vFRuws4wkvaXKK1uXZMAwAX4/t8ANaJo45iw/oQHNQ9q5xUzwgFmVJGXiga2BeN+zpX7Vf9vmsiIa2J+MUw==} + + '@protobufjs/path@1.1.2': + resolution: {integrity: sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==} + + '@protobufjs/pool@1.1.0': + resolution: {integrity: sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==} + + '@protobufjs/utf8@1.1.1': + resolution: {integrity: sha512-oOAWABowe8EAbMyWKM0tYDKi8Yaox52D+HWZhAIJqQXbqe0xI/GV7FhLWqlEKreMkfDjshR5FKgi3mnle0h6Eg==} + '@quansync/fs@1.0.0': resolution: {integrity: sha512-4TJ3DFtlf1L5LDMaM6CanJ/0lckGNtJcMjQ1NAV6zDmA0tEHKZtxNKin8EgPaVX1YzljbxckyT2tJrpQKAtngQ==} + '@redocly/ajv@8.11.2': + resolution: {integrity: sha512-io1JpnwtIcvojV7QKDUSIuMN/ikdOUd1ReEnUnMKGfDVridQZ31J0MmIuqwuRjWDZfmvr+Q0MqCcfHM2gTivOg==} + + '@redocly/ajv@8.18.1': + resolution: {integrity: sha512-Ifm/pP/tul1qmAecpbVxCBluVE32rKfjf8gYXH4xI2gCv9mRWFhJMHzkPDM4TXlxwPQYIFegymlsy8lXz7optA==} + + '@redocly/cli-otel@0.3.1': + resolution: {integrity: sha512-TbC4bK2zLtU/O9I2pszHPP0rtJOvFhQmEwQ/FHxERPu71fgKG8POUDP2jSiGmsXE7NdGSHBKqnf+y9Acn2jq5g==} + + '@redocly/cli@2.31.2': + resolution: {integrity: sha512-MqO0I6UvB4d7VOTOrYAbVwS+AgUZ4Bxp7d2vCbUseiEYGxArvkzXtwWNLfNKryXvUrVB8kfmvLuRp7LLHFvvDA==} + engines: {node: '>=22.12.0 || >=20.19.0 <21.0.0', npm: '>=10'} + hasBin: true + + '@redocly/config@0.22.0': + resolution: {integrity: sha512-gAy93Ddo01Z3bHuVdPWfCwzgfaYgMdaZPcfL7JZ7hWJoK9V0lXDbigTWkhiPFAaLWzbOJ+kbUQG1+XwIm0KRGQ==} + + '@redocly/config@0.48.2': + resolution: {integrity: sha512-DUHthTRdj+caAQWCtJae4yzvxaUDuwQkFsZFVaAEyORd8Bt8K2wYso61jYZuR/kQZaDejfUREtQTVVZ5VYTqgw==} + + '@redocly/openapi-core@1.34.14': + resolution: {integrity: sha512-y+xFx+Zz54Xhr8jUdnLENYnt7Y7GEDL6Q03ga7rTtX8DVwefX9H+hQEPgJp1nda7vdH+wJ9/HBVvyfBuW9x6rA==} + engines: {node: '>=18.17.0', npm: '>=9.5.0'} + + '@redocly/openapi-core@2.31.2': + resolution: {integrity: sha512-qKXAdKTRKqWArIWbMOHOELJGgfISMFD5pK0w5CaklH8LAn5M6BbyCocqz52IqMMUIiEyAsqb46a4vtuqPhLZwg==} + engines: {node: '>=22.12.0 || >=20.19.0 <21.0.0', npm: '>=10'} + + '@redocly/respect-core@2.31.2': + resolution: {integrity: sha512-M5zQV9M8uazCl46EVKKjWPo7M8EFNHFQOdovhqH+IfdAop5kHPi1fR1xSwrckak84XON0a+CqPU7z7+YCON0Bg==} + engines: {node: '>=22.12.0 || >=20.19.0 <21.0.0', npm: '>=10'} + '@replit/codemirror-css-color-picker@6.3.0': resolution: {integrity: sha512-19biDANghUm7Fz7L1SNMIhK48tagaWuCOHj4oPPxc7hxPGkTVY2lU/jVZ8tsbTKQPVG7BO2CBDzs7CBwb20t4A==} peerDependencies: @@ -2443,6 +2593,9 @@ packages: '@types/js-yaml@4.0.9': resolution: {integrity: sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==} + '@types/json-schema@7.0.15': + resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==} + '@types/mdast@4.0.4': resolution: {integrity: sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==} @@ -3228,6 +3381,12 @@ packages: peerDependencies: ajv: 4.11.8 - 8 + better-ajv-errors@2.0.3: + resolution: {integrity: sha512-t1vxUP+vYKsaYi/BbKo2K98nEAZmfi4sjwvmRT8aOPDzPJeAtLurfoIDazVkLILxO4K+Sw4YrLYnBQ46l6pePg==} + engines: {node: '>= 18.20.6'} + peerDependencies: + ajv: 4.11.8 - 8 + binary-extensions@2.3.0: resolution: {integrity: sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==} engines: {node: '>=8'} @@ -3318,6 +3477,9 @@ packages: resolution: {integrity: sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==} engines: {node: '>= 0.4'} + call-me-maybe@1.0.2: + resolution: {integrity: sha512-HpX65o1Hnr9HH25ojC1YGs7HCQLq0GCOibSaWER0eNpgJ/Z1MZv2mTc7+xh6WOPxbRVcmgbv4hGU+uSQ/2xFZQ==} + callsite@1.0.0: resolution: {integrity: sha512-0vdNRFXn5q+dtOqjfFtmtlI9N2eVZ7LMyEV2iKC5mEEFvSg/69Ml6b/WU2qF8W1nLRa0wiSrDT3Y5jOHZCwKPQ==} @@ -3389,6 +3551,9 @@ packages: cjs-module-lexer@1.4.3: resolution: {integrity: sha512-9z8TZaGM1pfswYeXrUpzPrkx8UnWYdhJclsiYMm6x/w5+nN+8Tf/LnAgfLGQCm59qAOxU8WwHEq2vNwF6i4j+Q==} + classnames@2.5.1: + resolution: {integrity: sha512-saHYOzhIQs6wy2sVxTM6bUDsQO4F50V9RQ22qBpEdCW+I+/Wmke2HOl6lS6dTpdxVhb88/I6+Hs+438c3lfUow==} + clean-css@5.3.3: resolution: {integrity: sha512-D5J+kHaVb/wKSFcyyV75uCn8fiY4sV38XJoe4CUyGQ+mOU/fMVYUdH1hJC+CJQ5uY3EnW27SbJYS4X8BiLrAFg==} engines: {node: '>= 10.0'} @@ -3421,6 +3586,9 @@ packages: resolution: {integrity: sha512-FxqpkPPwu1HjuN93Omfm4h8uIanXofW0RxVEW3k5RKx+mJJYSthzNhp32Kzxxy3YAEZ/Dc/EWN1vZRY0+kOhbw==} engines: {node: '>= 10'} + cliui@7.0.4: + resolution: {integrity: sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ==} + cliui@8.0.1: resolution: {integrity: sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==} engines: {node: '>=12'} @@ -3459,6 +3627,9 @@ packages: resolution: {integrity: sha512-ezmVcLR3xAVp8kYOm4GS45ZLLgIE6SPAFoduLr6hTDajwb3KZ2F46gulK3XpcwRFb5KKGCSezCBAY4Dw4HsyXA==} engines: {node: '>=18'} + colorette@1.4.0: + resolution: {integrity: sha512-Y2oEozpomLn7Q3HFP7dpww7AtMJplbM9lGZP6RDfHqmbeRjiwRg4n6VM6j4KLmRke85uWEI7JqF17f3pqdRA0g==} + colorette@2.0.20: resolution: {integrity: sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==} @@ -3550,6 +3721,9 @@ packages: resolution: {integrity: sha512-X8XDzyvYaA6msMyAM575CUoygY5b44QzLcGRKsK3MFmXcOvQa518dNPLsKYwkYsn72g3EiW+LE0ytd/FlqWmyw==} engines: {node: '>=18'} + core-js@3.49.0: + resolution: {integrity: sha512-es1U2+YTtzpwkxVLwAFdSpaIMyQaq0PBgm3YD1W3Qpsn1NAmO3KSgZfu+oGSWVu6NvLHoHCV/aYcsE5wiB7ALg==} + core-util-is@1.0.3: resolution: {integrity: sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==} @@ -3668,6 +3842,9 @@ packages: decache@4.6.2: resolution: {integrity: sha512-2LPqkLeu8XWHU8qNCS3kcF6sCcb5zIzvWaAHYSvPfwhdd7mHuah29NssMzrTYyHN4F5oFy2ko9OBYxegtU0FEw==} + decko@1.2.0: + resolution: {integrity: sha512-m8FnyHXV1QX+S1cl+KPFDIl6NMkxtKsy6+U/aYyjrOqWMuwAwYWu7ePqrsUHtDR5Y8Yk2pi/KIDSgF+vT4cPOQ==} + decode-named-character-reference@1.3.0: resolution: {integrity: sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==} @@ -3830,6 +4007,10 @@ packages: resolution: {integrity: sha512-1gxPBJpI/pcjQhKgIU91II6Wkay+dLcN3M6rf2uwP8hRur3HtQXjVrdAK3sjC0piaEuxzMwjXChcETiJl47lAQ==} engines: {node: '>=18'} + dotenv@16.4.7: + resolution: {integrity: sha512-47qPchRCykZC03FhkYAhrvwU4xDBFIj1QPqaarj6mdM/hgUzfPHcpkHJOn3mJAufFeeAxAzeGsr5X0M4k6fLZQ==} + engines: {node: '>=12'} + dotenv@16.6.1: resolution: {integrity: sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==} engines: {node: '>=12'} @@ -3965,6 +4146,9 @@ packages: resolution: {integrity: sha512-w+5mJ3GuFL+NjVtJlvydShqE1eN3h3PbI7/5LAsYJP/2qtuMXjfL2LpHSRqo4b4eSF5K/DH1JXKUAHSB2UW50g==} engines: {node: '>= 0.4'} + es6-promise@3.3.1: + resolution: {integrity: sha512-SOp9Phqvqn7jtEUxPWdWfWoLmyt2VaJ6MpvP9Comy1MceMXqE6bxvaTu4iaxpYYPzhny28Lc+M87/c2cPK6lDg==} + esast-util-from-estree@2.0.0: resolution: {integrity: sha512-4CyanoAudUSBAn5K13H4JhsMH6L9ZP7XbLVe/dKybkxMO7eDyLsT8UHl9TRNrU2Gr9nz+FovfSIjuXWJ81uVwQ==} @@ -4259,6 +4443,9 @@ packages: resolution: {integrity: sha512-dKx12eRCVIzqCxFGplyFKJMPvLEWgmNtUrpTiJIR5u97zEhRG8ySrtboPHZXx7daLxQVrl643cTzbab2tkQjxg==} engines: {node: '>= 0.4'} + foreach@2.0.6: + resolution: {integrity: sha512-k6GAGDyqLe9JaebCsFCoudPPWfihKu8pylYXRlqP1J7ms39iPoTtk2fviNglIeQEwdh0bQeKJ01ZPyuyQvKzwg==} + foreground-child@3.3.1: resolution: {integrity: sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==} engines: {node: '>=14'} @@ -4426,6 +4613,11 @@ packages: h3@1.15.11: resolution: {integrity: sha512-L3THSe2MPeBwgIZVSH5zLdBBU90TOxarvhK9d04IDY2AmVS8j2Jz2LIWtwsGOU3lu2I5jCN7FNvVfY2+XyF+mg==} + handlebars@4.7.9: + resolution: {integrity: sha512-4E71E0rpOaQuJR2A3xDZ+GM1HyWYv1clR58tC8emQNeQe3RH7MAzSbat+V0wG78LQBo6m6bzSG/L4pBuCsgnUQ==} + engines: {node: '>=0.4.7'} + hasBin: true + has-bigints@1.1.0: resolution: {integrity: sha512-R3pbpkcIqv2Pm3dUwgjclDRVmWpTJW2DcMzcIhEXEx1oh/CEMObMm3KLmRJOdvhM7o4uQBnwr8pzRK2sJWIqfg==} engines: {node: '>= 0.4'} @@ -4590,6 +4782,9 @@ packages: resolution: {integrity: sha512-S9wWkJ/VSY9/k4qcjG318bqJNruzE4HySUhFYknwmu6LBP97KLLfwNf+n4V1BHurvFNkSKLFnK/RsuUnRTf9Vw==} engines: {iojs: '>= 1.0.0', node: '>= 0.12.0'} + http2-client@1.3.5: + resolution: {integrity: sha512-EC2utToWl4RKfs5zd36Mxq7nzHHBuomZboI0yYL6Y0RmBgT7Sgkq4rQ0ezFTYoIsSs7Tm9SJe+o2FcAg6GBhGA==} + https-proxy-agent@7.0.6: resolution: {integrity: sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==} engines: {node: '>= 14'} @@ -4978,6 +5173,10 @@ packages: js-image-generator@1.0.4: resolution: {integrity: sha512-ckb7kyVojGAnArouVR+5lBIuwU1fcrn7E/YYSd0FK7oIngAkMmRvHASLro9Zt5SQdWToaI66NybG+OGxPw/HlQ==} + js-levenshtein@1.1.6: + resolution: {integrity: sha512-X2BB11YZtrRqY4EnQcLX5Rh373zbK4alC1FW7D7MBhL2gtcC17cTnr6DmfHZeS0s2rTHjUTMMHfG7gO8SSdw+g==} + engines: {node: '>=0.10.0'} + js-tokens@4.0.0: resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==} @@ -4990,9 +5189,16 @@ packages: engines: {node: '>=6'} hasBin: true + json-pointer@0.6.2: + resolution: {integrity: sha512-vLWcKbOaXlO+jvRy4qNd+TI1QUPZzfJj1tpJ3vAXDych5XJf93ftpUKe5pKCrzyIIwgBJcOcCVRUfqQP25afBw==} + json-schema-ref-resolver@3.0.0: resolution: {integrity: sha512-hOrZIVL5jyYFjzk7+y7n5JDzGlU8rfWDuYyHwGa2WA8/pcmMHezp2xsVwxrebD/Q9t8Nc5DboieySDpCp4WG4A==} + json-schema-to-ts@2.7.2: + resolution: {integrity: sha512-R1JfqKqbBR4qE8UyBR56Ms30LL62/nlhoz+1UkfI/VE7p54Awu919FZ6ZUPG8zIa3XB65usPJgr1ONVncUGSaQ==} + engines: {node: '>=16'} + json-schema-traverse@1.0.0: resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==} @@ -5013,6 +5219,10 @@ packages: jsonc-parser@3.3.1: resolution: {integrity: sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==} + jsonpath-rfc9535@1.3.0: + resolution: {integrity: sha512-3jFHya7oZ45aDxIIdx+/zQARahHXxFSMWBkcBUldfXpLS9VCXDJyTKt35kQfEXLqh0K3Ixw/9xFnvcDStaxh7Q==} + engines: {node: '>=20'} + jsonpointer@5.0.1: resolution: {integrity: sha512-p/nXbhSEcu3pZRdkW1OfJhpsVtW1gd4Wa1fnQc9YLiTfAjn0312eMKimbdIQzuZl9aa9xUGaRlP9T/CJE/ditQ==} engines: {node: '>=0.10.0'} @@ -5216,9 +5426,16 @@ packages: resolution: {integrity: sha512-TFYA4jnP7PVbmlBIfhlSe+WKxs9dklXMTEGcBCIvLhE/Tn3H6Gk1norupVW7m5Cnd4bLcr08AytbyV/xj7f/kQ==} engines: {node: '>= 12.0.0'} + long@5.3.2: + resolution: {integrity: sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==} + longest-streak@3.1.0: resolution: {integrity: sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==} + loose-envify@1.4.0: + resolution: {integrity: sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==} + hasBin: true + lower-case@2.0.2: resolution: {integrity: sha512-7fm3l3NAF9WfN6W3JOmf5drwpVqX78JtoGJ3A6W0a6ZnldM41w2fV5D490psKFTpMds8TJse/eHLFFsNHHjHgg==} @@ -5235,6 +5452,9 @@ packages: lru-cache@5.1.1: resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==} + lunr@2.3.9: + resolution: {integrity: sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==} + luxon@3.7.2: resolution: {integrity: sha512-vtEhXh/gNjI9Yg1u4jX/0YVPMvxzHuGgCm6tC5kZyb08yjGWGnqAjGJvcXbqQR2P3MyMEFnRbpcdFS6PBcLqew==} engines: {node: '>=12'} @@ -5264,6 +5484,9 @@ packages: resolution: {integrity: sha512-K6K2NgKnTXimT3779/4KxSvobxOtMmx1LBZ3NwRxT/MDIR3Br/fQ4Q+WCX5QxjyUR8zg5+RV9Tbf2c5pAWTD2A==} engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0} + mark.js@8.11.1: + resolution: {integrity: sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==} + markdown-extensions@2.0.0: resolution: {integrity: sha512-o5vL7aDWatOTX8LzaS1WMoaoxIiLRQJuIKKe2wAw6IeULDHaqbiqiggmx+pKvZDb1Sj+pE46Sn1T7lCqfFtg1Q==} engines: {node: '>=16'} @@ -5301,6 +5524,11 @@ packages: engines: {node: '>= 20'} hasBin: true + marked@4.3.0: + resolution: {integrity: sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==} + engines: {node: '>= 12'} + hasBin: true + math-intrinsics@1.1.0: resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==} engines: {node: '>= 0.4'} @@ -5558,6 +5786,35 @@ packages: mlly@1.8.2: resolution: {integrity: sha512-d+ObxMQFmbt10sretNDytwt85VrbkhhUA/JBGm1MPaWJ65Cl4wOgLaB1NYvJSZ0Ef03MMEU/0xpPMXUIQ29UfA==} + mobx-react-lite@4.1.1: + resolution: {integrity: sha512-iUxiMpsvNraCKXU+yPotsOncNNmyeS2B5DKL+TL6Tar/xm+wwNJAubJmtRSeAoYawdZqwv8Z/+5nPRHeQxTiXg==} + peerDependencies: + mobx: ^6.9.0 + react: ^16.8.0 || ^17 || ^18 || ^19 + react-dom: '*' + react-native: '*' + peerDependenciesMeta: + react-dom: + optional: true + react-native: + optional: true + + mobx-react@9.2.0: + resolution: {integrity: sha512-dkGWCx+S0/1mfiuFfHRH8D9cplmwhxOV5CkXMp38u6rQGG2Pv3FWYztS0M7ncR6TyPRQKaTG/pnitInoYE9Vrw==} + peerDependencies: + mobx: ^6.9.0 + react: ^16.8.0 || ^17 || ^18 || ^19 + react-dom: '*' + react-native: '*' + peerDependenciesMeta: + react-dom: + optional: true + react-native: + optional: true + + mobx@6.15.3: + resolution: {integrity: sha512-6+ZSYDs5zgH5CdGfEU2q2Lsa5PztVryL1ys7kAImTU25n2A9LAMj/yneVsQpd03MfwMLDQF+7kakJR9Z+cQxSw==} + modern-tar@0.7.5: resolution: {integrity: sha512-YTefgdpKKFgoTDbEUqXqgUJct2OG6/4hs4XWLsxcHkDLj/x/V8WmKIRppPnXP5feQ7d1vuYWSp3qKkxfwaFaxA==} engines: {node: '>=18.0.0'} @@ -5637,6 +5894,9 @@ packages: resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==} engines: {node: '>= 0.6'} + neo-async@2.6.2: + resolution: {integrity: sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==} + neotraverse@0.6.18: resolution: {integrity: sha512-Z4SmBUweYa09+o6pG+eASabEpP6QkQ70yHj351pQoEXIs8uHbaU2DWVmzBANKgflPa47A50PtB2+NgRpQvr7vA==} engines: {node: '>= 10'} @@ -5672,6 +5932,10 @@ packages: resolution: {integrity: sha512-pyFS63ptit/P5WqUkt+UUfe+4oevH+bFeIiPPdfb0pFeYEu/1ELnJu5l+5EcTKYL5M7zaAa7S8ddywgXypqKCw==} engines: {node: '>= 0.4'} + node-fetch-h2@2.3.0: + resolution: {integrity: sha512-ofRW94Ab0T4AOh5Fk8t0h8OBWrmjb0SSB20xh1H8YnPV9EJ+f5AMoYSUQ2zgJ4Iq2HAK0I2l5/Nequ8YzFS3Hg==} + engines: {node: 4.x || >=6.0.0} + node-fetch-native@1.6.7: resolution: {integrity: sha512-g9yhqoedzIUm0nTnTqAQvueMPVOuIY16bqgAJJC8XOOubYFNwz6IER9qs0Gq2Xd0+CecCKFjtdDTMA4u4xG06Q==} @@ -5699,6 +5963,9 @@ packages: node-mock-http@1.0.4: resolution: {integrity: sha512-8DY+kFsDkNXy1sJglUfuODx1/opAGJGyrTuFqEoN90oRc2Vk0ZbD4K2qmKXBBEhZQzdKHIVfEJpDU8Ak2NJEvQ==} + node-readfiles@0.2.0: + resolution: {integrity: sha512-SU00ZarexNlE4Rjdm83vglt5Y9yiQ+XI1XpflWlb7q7UTN1JUItm69xMeiQCTxtTfnzt+83T8Cx+vI2ED++VDA==} + node-releases@2.0.37: resolution: {integrity: sha512-1h5gKZCF+pO/o3Iqt5Jp7wc9rH3eJJ0+nh/CIoiRwjRxde/hAHyLPXYN4V3CqKAbiZPSeJFSWHmJsbkicta0Eg==} @@ -5750,6 +6017,26 @@ packages: nth-check@2.1.1: resolution: {integrity: sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==} + oas-kit-common@1.0.8: + resolution: {integrity: sha512-pJTS2+T0oGIwgjGpw7sIRU8RQMcUoKCDWFLdBqKB2BNmGpbBMH2sdqAaOXUg8OzonZHU0L7vfJu1mJFEiYDWOQ==} + + oas-linter@3.2.2: + resolution: {integrity: sha512-KEGjPDVoU5K6swgo9hJVA/qYGlwfbFx+Kg2QB/kd7rzV5N8N5Mg6PlsoCMohVnQmo+pzJap/F610qTodKzecGQ==} + + oas-resolver@2.5.6: + resolution: {integrity: sha512-Yx5PWQNZomfEhPPOphFbZKi9W93CocQj18NlD2Pa4GWZzdZpSJvYwoiuurRI7m3SpcChrnO08hkuQDL3FGsVFQ==} + hasBin: true + + oas-schema-walker@1.1.5: + resolution: {integrity: sha512-2yucenq1a9YPmeNExoUa9Qwrt9RFkjqaMAA1X+U7sbb0AqBeTIdMHky9SQQ6iN94bO5NW0W4TRYXerG+BdAvAQ==} + + oas-validator@5.0.8: + resolution: {integrity: sha512-cu20/HE5N5HKqVygs3dt94eYJfBi0TsZvPVXDhbXQHiEityDN+RROTleefoKRKKJ9dFAF2JBkDHgvWj0sjKGmw==} + + object-assign@4.1.1: + resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==} + engines: {node: '>=0.10.0'} + object-inspect@1.13.4: resolution: {integrity: sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==} engines: {node: '>= 0.4'} @@ -5826,6 +6113,9 @@ packages: resolution: {integrity: sha512-smsWv2LzFjP03xmvFoJ331ss6h+jixfA4UUV/Bsiyuu4YJPfN+FIQGOIiv4w9/+MoHkfkJ22UIaQWRVFRfH6Vw==} engines: {node: '>=20'} + openapi-sampler@1.7.3: + resolution: {integrity: sha512-Qgy2+Z7xR3l7kXurtzi1PCtzAINkFKhBADBe/8cidC2fQrLUQTudLiJjQDnqJXoisWAR6zaHhC0hP6Hn5vja+g==} + ora@5.4.1: resolution: {integrity: sha512-5b6Y85tPxZZ7QytO+BQzysW31HJku27cRIlkbAXaNx+BdcVi+LlRFmVXzeF6a7JCwJpyw5c4b+YSVImQIrBpuQ==} engines: {node: '>=10'} @@ -5834,6 +6124,9 @@ packages: resolution: {integrity: sha512-zBd1G8HkewNd2A8oQ8c6BN/f/c9EId7rSUueOLGu28govmUctXmM+3765GwsByv9nYUdrLqHphXlYIc86saYsg==} engines: {node: '>=18'} + outdent@0.8.0: + resolution: {integrity: sha512-KiOAIsdpUTcAXuykya5fnVVT+/5uS0Q1mrkRHcF89tpieSmY33O/tmc54CqwA+bfhbtEfZUNLHaPUiB9X3jt1A==} + own-keys@1.0.1: resolution: {integrity: sha512-qFOyK5PjiWZd+QQIh+1jhdb9LpxTF0qs7Pm8o5QHYZ0M3vKqSqzsZaEB6oWlxZ+q2sJBMI/Ktgd2N5ZwQoRHfg==} engines: {node: '>= 0.4'} @@ -6006,6 +6299,9 @@ packages: perfect-debounce@2.1.0: resolution: {integrity: sha512-LjgdTytVFXeUgtHZr9WYViYSM/g8MkcTPYDlPa3cDqMirHjKiSZPYd6DoL7pK8AJQr+uWkQvCjHNdiMqsrJs+g==} + perfect-scrollbar@1.5.6: + resolution: {integrity: sha512-rixgxw3SxyJbCaSpo1n35A/fwI1r2rdwMKOTCg/AcG+xOEyZcE8UHVjpZMFCVImzsFoCZeJTT+M/rdEIQYO2nw==} + pg-cloudflare@1.3.0: resolution: {integrity: sha512-6lswVVSztmHiRtD6I8hw4qP/nDm1EJbKMRhf3HCYaqud7frGysPv7FYJ5noZQdhQtN2xJnimfMtvQq21pdbzyQ==} @@ -6076,6 +6372,14 @@ packages: pkg-types@2.3.0: resolution: {integrity: sha512-SIqCzDRg0s9npO5XQ3tNZioRY1uK06lA41ynBC1YmFTmnY6FjUjVt6s4LoADmwoig1qqD0oK8h1p/8mlMx8Oig==} + pluralize@8.0.0: + resolution: {integrity: sha512-Nc3IT5yHzflTfbjgqWcCPpo7DaKy4FnpB0l/zCAW0Tc7jxAiuqSxHasntB3D7887LSrA93kDJ9IXovxJYxyLCA==} + engines: {node: '>=4'} + + polished@4.3.1: + resolution: {integrity: sha512-OBatVyC/N7SCW/FaDHrSd+vn0o5cS855TOmYi4OkdWUMSJCET/xip//ch8xGUvtr3i44X9LVyWwQlRMTN3pwSA==} + engines: {node: '>=10'} + possible-typed-array-names@1.1.0: resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==} engines: {node: '>= 0.4'} @@ -6225,12 +6529,19 @@ packages: resolution: {integrity: sha512-cdGef/drWFoydD1JsMzuFf8100nZl+GT+yacc2bEced5f9Rjk4z+WtFUTBu9PhOi9j/jfmBPu0mMEY4wIdAF8A==} engines: {node: '>= 0.6.0'} + prop-types@15.8.1: + resolution: {integrity: sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg==} + property-information@7.1.0: resolution: {integrity: sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ==} proto-list@1.2.4: resolution: {integrity: sha512-vtK/94akxsTMhe0/cbfpR+syPuszcuwhqVjJq26CuNDgFGj682oRBXOP5MJpv2r7JtE8MsiepGIqvvOTBwn2vA==} + protobufjs@7.6.0: + resolution: {integrity: sha512-LtESOsMPTZgyYtwxhvdgdjGL0HmXEaRA/hVD6sol4zA60hVXXXP/SGmxnqDbgGE8gy7pYex7cym+5vYPcmaXBQ==} + engines: {node: '>=12.0.0'} + proxy-addr@2.0.7: resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==} engines: {node: '>= 0.10'} @@ -6280,6 +6591,9 @@ packages: resolution: {integrity: sha512-iv7LhNVO047HzYR3InF6pUcUsPQiHTM1Qal51DcGSuZFBil1aBBWG5eHPNek7bvILMaYJ/8RU1e8w1AMdHmLQQ==} engines: {node: '>= 0.8'} + randombytes@2.1.0: + resolution: {integrity: sha512-vYl3iOX+4CKUWuxGi9Ukhie6fsqXqS9FE2Zaic4tNFD2N2QQaXOMFbuKK4QmDHC0JO6B1Zp41J0LpT0oR68amQ==} + range-parser@1.2.1: resolution: {integrity: sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==} engines: {node: '>= 0.6'} @@ -6297,10 +6611,18 @@ packages: peerDependencies: react: ^19.2.5 + react-is@16.13.1: + resolution: {integrity: sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ==} + react-refresh@0.18.0: resolution: {integrity: sha512-QgT5//D3jfjJb6Gsjxv0Slpj23ip+HtOpnNgnb2S5zU3CB26G/IDPGoy4RJB42wzFE46DRsstbW6tKHoKbhAxw==} engines: {node: '>=0.10.0'} + react-tabs@6.1.1: + resolution: {integrity: sha512-CPiuKoMFf89B7QlbFfdBD9XmUWiE3qudQputMVZB8GQvPJZRX/gqjDaDWOPDwGinEfpJKEuBCkGt83Tt4efeyA==} + peerDependencies: + react: ^18.0.0 || ^19.0.0 + react@19.2.5: resolution: {integrity: sha512-llUJLzz1zTUBrskt2pwZgLq59AemifIftw4aB7JxOqf1HY2FDaGDxgwpAPVzHU1kdWabH7FauP4i1oEeer2WCA==} engines: {node: '>=0.10.0'} @@ -6365,10 +6687,23 @@ packages: recma-stringify@1.0.0: resolution: {integrity: sha512-cjwII1MdIIVloKvC9ErQ+OgAtwHBmcZ0Bg4ciz78FtbT8In39aAYbaA7zvxQ61xVMSPE8WxhLwLbhif4Js2C+g==} + redoc@2.5.1: + resolution: {integrity: sha512-LmqA+4A3CmhTllGG197F0arUpmChukAj9klfSdxNRemT9Hr07xXr7OGKu4PHzBs359sgrJ+4JwmOlM7nxLPGMg==} + engines: {node: '>=6.9', npm: '>=3.0.0'} + peerDependencies: + core-js: ^3.1.4 + mobx: ^6.0.4 + react: ^16.8.4 || ^17.0.0 || ^18.0.0 || ^19.0.0 + react-dom: ^16.8.4 || ^17.0.0 || ^18.0.0 || ^19.0.0 + styled-components: ^4.1.1 || ^5.1.1 || ^6.0.5 + reflect.getprototypeof@1.0.10: resolution: {integrity: sha512-00o4I+DVrefhv+nX0ulyi3biSHCPDe+yLv5o/p6d/UVlirijB8E16FtfwSAi4g3tcqrQ4lRAqQSoFEZJehYEcw==} engines: {node: '>= 0.4'} + reftools@1.1.9: + resolution: {integrity: sha512-OVede/NQE13xBQ+ob5CKd5KyeJYU2YInb1bmV4nRoOfquZPkAkxuOXicSe1PvqIuZZ4kD13sPKBbR7UFDmli6w==} + regex-recursion@6.0.2: resolution: {integrity: sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==} @@ -6687,6 +7022,24 @@ packages: resolution: {integrity: sha512-eAVKTMedR5ckPo4xne/PjYQYrU3qx78gtJZ+sHlXEg5IHhhoQhMfZVzetTYuaJS0L2Ef3AcCRzCHV8T0WI6nIQ==} engines: {node: '>=20'} + should-equal@2.0.0: + resolution: {integrity: sha512-ZP36TMrK9euEuWQYBig9W55WPC7uo37qzAEmbjHz4gfyuXrEUgF8cUvQVO+w+d3OMfPvSRQJ22lSm8MQJ43LTA==} + + should-format@3.0.3: + resolution: {integrity: sha512-hZ58adtulAk0gKtua7QxevgUaXTTXxIi8t41L3zo9AHvjXO1/7sdLECuHeIN2SRtYXpNkmhoUP2pdeWgricQ+Q==} + + should-type-adaptors@1.1.0: + resolution: {integrity: sha512-JA4hdoLnN+kebEp2Vs8eBe9g7uy0zbRo+RMcU0EsNy+R+k049Ki+N5tT5Jagst2g7EAja+euFuoXFCa8vIklfA==} + + should-type@1.4.0: + resolution: {integrity: sha512-MdAsTu3n25yDbIe1NeN69G4n6mUnJGtSJHygX3+oN0ZbO3DTiATnf7XnYJdGT42JCXurTb1JI0qOBR65shvhPQ==} + + should-util@1.0.1: + resolution: {integrity: sha512-oXF8tfxx5cDk8r2kYqlkUJzZpDBqVY/II2WhvU0n9Y3XYvAYRmeaf1PvvIvTgPnv4KJ+ES5M0PyDq5Jp+Ygy2g==} + + should@13.2.3: + resolution: {integrity: sha512-ggLesLtu2xp+ZxI+ysJTmNjh2U0TsC+rQ/pfED9bUZZ4DKefP27D+7YJVVTvKsmjLpIi9jAa7itwDGkDDmt1GQ==} + side-channel-list@1.0.1: resolution: {integrity: sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==} engines: {node: '>= 0.4'} @@ -6714,6 +7067,9 @@ packages: resolution: {integrity: sha512-WszCLXwT4h2k1ufIXAgsbiTOazqqevFCIncOuUBZJ91DdvWcC5+OFkluWRQPrcuSYd8fjq+o2y1QfWqYMoAToQ==} hasBin: true + simple-websocket@9.1.0: + resolution: {integrity: sha512-8MJPnjRN6A8UCp1I+H/dSFyjwJhp6wta4hsVRhjf8w9qBHRzxYt14RaOcjvQnhD1N4yKOddEjflwMnQM4VtXjQ==} + sirv@3.0.2: resolution: {integrity: sha512-2wcC/oGxHis/BoHkkPwldgiPSYcpZK3JU28WoMVv55yHJgcZ8rlXvuG9iZggz+sU1d4bRgIGASwyWqjxu3FM0g==} engines: {node: '>=18'} @@ -6737,6 +7093,10 @@ packages: resolution: {integrity: sha512-stxByr12oeeOyY2BlviTNQlYV5xOj47GirPr4yA1hE9JCtxfQN0+tVbkxwCtYDQWhEKWFHsEK48ORg5jrouCAg==} engines: {node: '>=20'} + slugify@1.4.7: + resolution: {integrity: sha512-tf+h5W1IrjNm/9rKKj0JU2MDMruiopx0jjVA5zCdBtcGjfp0+c5rHw/zADLC3IeKlGHtVbHtpfzvYA0OYT+HKg==} + engines: {node: '>=8.0.0'} + smartypants@0.2.2: resolution: {integrity: sha512-TzobUYoEft/xBtb2voRPryAUIvYguG0V7Tt3de79I1WfXgCwelqVsGuZSnu3GFGRZhXR90AeEYIM+icuB/S06Q==} hasBin: true @@ -6893,6 +7253,9 @@ packages: std-env@4.1.0: resolution: {integrity: sha512-Rq7ybcX2RuC55r9oaPVEW7/xu3tj8u4GeBYHBWCychFtzMIr86A7e3PPEBPT37sHStKX3+TiX/Fr/ACmJLVlLQ==} + stickyfill@1.1.1: + resolution: {integrity: sha512-GCp7vHAfpao+Qh/3Flh9DXEJ/qSi0KJwJw6zYlZOtRYXWUIpMM6mC2rIep/dK8RQqwW0KxGJIllmjPIBOGN8AA==} + stop-iteration-iterator@1.1.0: resolution: {integrity: sha512-eLoXW/DHyl62zxY4SCaIgnRhuMr6ri4juEYARS8E6sCEqzKpOiE521Ucofdx+KnDZl5xmvGYaaKCk5FEOxJCoQ==} engines: {node: '>= 0.4'} @@ -6986,6 +7349,25 @@ packages: style-to-object@1.0.14: resolution: {integrity: sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw==} + styled-components@6.4.1: + resolution: {integrity: sha512-ADu2dF53esUzzM4I0ewxhxFtsDd6v4V6dNkg3vG0iFKhnt06sJneTZnRvujAosZwW0XD58IKgGMQoqri4wHRqg==} + engines: {node: '>= 16'} + peerDependencies: + css-to-react-native: '>= 3.2.0' + react: '>= 16.8.0' + react-dom: '>= 16.8.0' + react-native: '>= 0.68.0' + peerDependenciesMeta: + css-to-react-native: + optional: true + react-dom: + optional: true + react-native: + optional: true + + stylis@4.3.6: + resolution: {integrity: sha512-yQ3rwFWRfwNUY7H5vpU0wfdkNSnvnJinhF9830Swlaxl03zsOjCfmX0ugac+3LtK0lYSgwL/KXc8oYL3mG4YFQ==} + suf-log@2.5.3: resolution: {integrity: sha512-KvC8OPjzdNOe+xQ4XWJV2whQA0aM1kGVczMQ8+dStAO6KfEB140JEVQ9dE76ONZ0/Ylf67ni4tILPJB41U0eow==} @@ -7018,6 +7400,10 @@ packages: engines: {node: '>=16'} hasBin: true + swagger2openapi@7.0.8: + resolution: {integrity: sha512-upi/0ZGkYgEcLeGieoz8gT74oWHA0E7JivX7aN9mAf+Tc7BQoRBvnIGHoPDw+f9TXTW4s6kGYCZJtauP6OYp7g==} + hasBin: true + swrv@1.2.0: resolution: {integrity: sha512-lH/g4UcNyj+7lzK4eRGT4C68Q4EhQ6JtM9otPRIASfhhzfLWtbZPHcMuhuba7S9YVYuxkMUGImwMyGpfbkH07A==} peerDependencies: @@ -7149,6 +7535,9 @@ packages: resolution: {integrity: sha512-QVsbr1WhGLq2F0oDyYbqtOXcf3gcnL8C9H5EX8bBwAr8ZWvWGJzukpPrDrWgJMrNtgDbo74BIjI4kJu3q2xQWw==} engines: {node: '>=18.18.0'} + ts-algebra@1.2.2: + resolution: {integrity: sha512-kloPhf1hq3JbCPOTYoOWDKxebWjNb2o/LKnNfkWhxVVisFFmMJPPdJeGoGmM+iRLyoXAR61e08Pb+vUXINg8aA==} + ts-api-utils@2.5.0: resolution: {integrity: sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==} engines: {node: '>=18.12'} @@ -7244,10 +7633,19 @@ packages: ufo@1.6.3: resolution: {integrity: sha512-yDJTmhydvl5lJzBmy/hyOAA0d+aqCBuwl818haVdYCRrWV84o7YyeVm4QlVHStqNrrJSTb6jKuFAVqAFsr+K3Q==} + uglify-js@3.19.3: + resolution: {integrity: sha512-v3Xu+yuwBXisp6QYTcH4UbH+xYJXqnq2m/LtQVWKWzYc1iehYnLixoQDN9FH6/j9/oybfd6W9Ghwkl8+UMKTKQ==} + engines: {node: '>=0.8.0'} + hasBin: true + uid-safe@2.1.5: resolution: {integrity: sha512-KPHm4VL5dDXKz01UuEd88Df+KzynaohSL9fBh096KWAxSKZQDI2uBrVqtvRM4rwrIrRRKsdLNML/lnaaVSRioA==} engines: {node: '>= 0.8'} + ulid@2.4.0: + resolution: {integrity: sha512-fIRiVTJNcSRmXKPZtGzFQv9WRrZ3M9eoptl/teFJvjOzmpU+/K/JH6HZ8deBfb5vMEpicJcLn7JmvdknlMq7Zg==} + hasBin: true + ulid@3.0.1: resolution: {integrity: sha512-dPJyqPzx8preQhqq24bBG1YNkvigm87K8kVEHCD+ruZg24t6IFEFv00xMWfxcC4djmFtiTLdFuADn4+DOz6R7Q==} hasBin: true @@ -7278,6 +7676,10 @@ packages: undici-types@7.19.2: resolution: {integrity: sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg==} + undici@6.24.0: + resolution: {integrity: sha512-lVLNosgqo5EkGqh5XUDhGfsMSoO8K0BAN0TyJLvwNRSl4xWGZlCVYsAIpa/OpA3TvmnM01GWcoKmc3ZWo5wKKA==} + engines: {node: '>=18.17'} + unhead@2.1.13: resolution: {integrity: sha512-jO9M1sI6b2h/1KpIu4Jeu+ptumLmUKboRRLxys5pYHFeT+lqTzfNHbYUX9bxVDhC1FBszAGuWcUVlmvIPsah8Q==} @@ -7478,12 +7880,23 @@ packages: uqr@0.1.3: resolution: {integrity: sha512-0rjE8iEJe4YmT9TOhwsZtqCMRLc5DXZUI2UEYUUg63ikBkqqE5EYWaI0etFe/5KUcmcYwLih2RND1kq+hrUJXA==} + uri-js-replace@1.0.1: + resolution: {integrity: sha512-W+C9NWNLFOoBI2QWDp4UT9pv65r2w5Cx+3sTYFvtMdDBxkKt1syCqsUdSFAChbEe1uK5TfS04wt/nGwmaeIQ0g==} + + url-template@2.0.8: + resolution: {integrity: sha512-XdVKMF4SJ0nP/O7XIPB0JwAEuT9lDIYnNsK8yGVe43y0AWoKeJNdv3ZNWh7ksJ6KqQFjOO6ox/VEitLnaVNufw==} + urlpattern-polyfill@10.1.0: resolution: {integrity: sha512-IGjKp/o0NL3Bso1PymYURCJxMPNAf/ILOpendP9f5B6e1rTJgdgiOvgfoT8VxCAdY+Wisb9uhGaJJf3yZ2V9nw==} urlpattern-polyfill@8.0.2: resolution: {integrity: sha512-Qp95D4TPJl1kC9SKigDcqgyM2VDVO4RiJc2d4qe5GrYm+zbIQCWWKAFaJNQ4BhdFeDGwBmAxqJBwWSJDb9T3BQ==} + use-sync-external-store@1.6.0: + resolution: {integrity: sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==} + peerDependencies: + react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 + util-deprecate@1.0.2: resolution: {integrity: sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==} @@ -7817,6 +8230,9 @@ packages: resolution: {integrity: sha512-LZNJgPzfKR+/J3cHkxcpHKpKKvGfDZVPS4hfJCc4cCG0CgYzvlD6yE/S3CIL/Yt91ak327YCpiF/0MyeZHEHKA==} engines: {node: '>= 12.0.0'} + wordwrap@1.0.0: + resolution: {integrity: sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q==} + wrap-ansi@10.0.0: resolution: {integrity: sha512-SGcvg80f0wUy2/fXES19feHMz8E0JoXv2uNgHOu4Dgi2OrCy1lqwFYEJz1BLbDI0exjPMe/ZdzZ/YpGECBG/aQ==} engines: {node: '>=20'} @@ -7840,6 +8256,18 @@ packages: resolution: {integrity: sha512-+QU2zd6OTD8XWIJCbffaiQeH9U73qIqafo1x6V1snCWYGJf6cVE0cDR4D8xRzcEnfI21IFrUPzPGtcPf8AC+Rw==} engines: {node: ^14.17.0 || ^16.13.0 || >=18.0.0} + ws@7.5.10: + resolution: {integrity: sha512-+dbF1tHwZpXcbOJdVOkzLDxZP1ailvSxM6ZweXTegylPny803bFhA+vqBYw4s31NSAk4S2Qz+AKXK9a4wkdjcQ==} + engines: {node: '>=8.3.0'} + peerDependencies: + bufferutil: ^4.0.1 + utf-8-validate: ^5.0.2 + peerDependenciesMeta: + bufferutil: + optional: true + utf-8-validate: + optional: true + ws@8.19.0: resolution: {integrity: sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==} engines: {node: '>=10.0.0'} @@ -7887,10 +8315,17 @@ packages: resolution: {integrity: sha512-YgvUTfwqyc7UXVMrB+SImsVYSmTS8X/tSrtdNZMImM+n7+QTriRXyXim0mBrTXNeqzVF0KWGgHPeiyViFFrNDw==} engines: {node: '>=18'} + yaml-ast-parser@0.0.43: + resolution: {integrity: sha512-2PTINUwsRqSd+s8XxKaJWQlUuEMHJQyEuh2edBbW8KNJz0SJPwUSD2zRWqezFEdN7IzAgeuYHFUCF7o8zRdZ0A==} + yaml-language-server@1.20.0: resolution: {integrity: sha512-qhjK/bzSRZ6HtTvgeFvjNPJGWdZ0+x5NREV/9XZWFjIGezew2b4r5JPy66IfOhd5OA7KeFwk1JfmEbnTvev0cA==} hasBin: true + yaml@1.10.3: + resolution: {integrity: sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA==} + engines: {node: '>= 6'} + yaml@2.7.1: resolution: {integrity: sha512-10ULxpnOCQXxJvBgxsn9ptjq6uviG/htZKk9veJGhlqn3w/DxQ631zFF+nlQXLwmImeS5amR2dl2U8sg6U9jsQ==} engines: {node: '>= 14'} @@ -7901,6 +8336,10 @@ packages: engines: {node: '>= 14.6'} hasBin: true + yargs-parser@20.2.9: + resolution: {integrity: sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w==} + engines: {node: '>=10'} + yargs-parser@21.1.1: resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==} engines: {node: '>=12'} @@ -7909,6 +8348,10 @@ packages: resolution: {integrity: sha512-rwu/ClNdSMpkSrUb+d6BRsSkLUq1fmfsY6TOpYzTwvwkg1/NRG85KBy3kq++A8LKQwX6lsu+aWad+2khvuXrqw==} engines: {node: ^20.19.0 || ^22.12.0 || >=23} + yargs@17.0.1: + resolution: {integrity: sha512-xBBulfCc8Y6gLFcrPvtqKz9hz8SO0l1Ni8GgDekvBX2ro0HRQImDGnikfc33cgzcYUSncapnNcZDjVFIH3f6KQ==} + engines: {node: '>=12'} + yargs@17.7.2: resolution: {integrity: sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==} engines: {node: '>=12'} @@ -8668,6 +9111,12 @@ snapshots: tslib: 2.8.1 optional: true + '@emotion/is-prop-valid@1.4.0': + dependencies: + '@emotion/memoize': 0.9.0 + + '@emotion/memoize@0.9.0': {} + '@envelop/instrumentation@1.0.0': dependencies: '@whatwg-node/promise-helpers': 1.3.2 @@ -8831,6 +9280,8 @@ snapshots: '@esbuild/win32-x64@0.27.7': optional: true + '@exodus/schemasafe@1.3.0': {} + '@expressive-code/core@0.41.7': dependencies: '@ctrl/tinycolor': 4.2.0 @@ -8864,6 +9315,8 @@ snapshots: dependencies: '@expressive-code/core': 0.41.7 + '@faker-js/faker@7.6.0': {} + '@fastify/accept-negotiator@2.0.1': {} '@fastify/ajv-compiler@4.0.5': @@ -9828,6 +10281,8 @@ snapshots: - rollup - supports-color + '@noble/hashes@1.8.0': {} + '@nodable/entities@1.1.0': {} '@nodelib/fs.scandir@2.1.5': @@ -10023,6 +10478,10 @@ snapshots: dependencies: '@opentelemetry/api': 1.9.1 + '@opentelemetry/api-logs@0.214.0': + dependencies: + '@opentelemetry/api': 1.9.1 + '@opentelemetry/api@1.8.0': {} '@opentelemetry/api@1.9.0': {} @@ -10033,11 +10492,29 @@ snapshots: dependencies: '@opentelemetry/api': 1.9.0 + '@opentelemetry/context-async-hooks@2.6.1(@opentelemetry/api@1.9.1)': + dependencies: + '@opentelemetry/api': 1.9.1 + '@opentelemetry/core@1.30.1(@opentelemetry/api@1.9.0)': dependencies: '@opentelemetry/api': 1.9.0 '@opentelemetry/semantic-conventions': 1.28.0 + '@opentelemetry/core@2.6.1(@opentelemetry/api@1.9.1)': + dependencies: + '@opentelemetry/api': 1.9.1 + '@opentelemetry/semantic-conventions': 1.40.0 + + '@opentelemetry/exporter-trace-otlp-http@0.214.0(@opentelemetry/api@1.9.1)': + dependencies: + '@opentelemetry/api': 1.9.1 + '@opentelemetry/core': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/otlp-exporter-base': 0.214.0(@opentelemetry/api@1.9.1) + '@opentelemetry/otlp-transformer': 0.214.0(@opentelemetry/api@1.9.1) + '@opentelemetry/resources': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/sdk-trace-base': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/instrumentation@0.203.0(@opentelemetry/api@1.9.0)(supports-color@10.2.2)': dependencies: '@opentelemetry/api': 1.9.0 @@ -10047,6 +10524,23 @@ snapshots: transitivePeerDependencies: - supports-color + '@opentelemetry/otlp-exporter-base@0.214.0(@opentelemetry/api@1.9.1)': + dependencies: + '@opentelemetry/api': 1.9.1 + '@opentelemetry/core': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/otlp-transformer': 0.214.0(@opentelemetry/api@1.9.1) + + '@opentelemetry/otlp-transformer@0.214.0(@opentelemetry/api@1.9.1)': + dependencies: + '@opentelemetry/api': 1.9.1 + '@opentelemetry/api-logs': 0.214.0 + '@opentelemetry/core': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/resources': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/sdk-logs': 0.214.0(@opentelemetry/api@1.9.1) + '@opentelemetry/sdk-metrics': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/sdk-trace-base': 2.6.1(@opentelemetry/api@1.9.1) + protobufjs: 7.6.0 + '@opentelemetry/propagator-b3@1.30.1(@opentelemetry/api@1.9.0)': dependencies: '@opentelemetry/api': 1.9.0 @@ -10063,6 +10557,26 @@ snapshots: '@opentelemetry/core': 1.30.1(@opentelemetry/api@1.9.0) '@opentelemetry/semantic-conventions': 1.28.0 + '@opentelemetry/resources@2.6.1(@opentelemetry/api@1.9.1)': + dependencies: + '@opentelemetry/api': 1.9.1 + '@opentelemetry/core': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/semantic-conventions': 1.40.0 + + '@opentelemetry/sdk-logs@0.214.0(@opentelemetry/api@1.9.1)': + dependencies: + '@opentelemetry/api': 1.9.1 + '@opentelemetry/api-logs': 0.214.0 + '@opentelemetry/core': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/resources': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/semantic-conventions': 1.40.0 + + '@opentelemetry/sdk-metrics@2.6.1(@opentelemetry/api@1.9.1)': + dependencies: + '@opentelemetry/api': 1.9.1 + '@opentelemetry/core': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/resources': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/sdk-trace-base@1.30.1(@opentelemetry/api@1.9.0)': dependencies: '@opentelemetry/api': 1.9.0 @@ -10070,6 +10584,13 @@ snapshots: '@opentelemetry/resources': 1.30.1(@opentelemetry/api@1.9.0) '@opentelemetry/semantic-conventions': 1.28.0 + '@opentelemetry/sdk-trace-base@2.6.1(@opentelemetry/api@1.9.1)': + dependencies: + '@opentelemetry/api': 1.9.1 + '@opentelemetry/core': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/resources': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/semantic-conventions': 1.40.0 + '@opentelemetry/sdk-trace-node@1.30.1(@opentelemetry/api@1.9.0)': dependencies: '@opentelemetry/api': 1.9.0 @@ -10080,8 +10601,17 @@ snapshots: '@opentelemetry/sdk-trace-base': 1.30.1(@opentelemetry/api@1.9.0) semver: 7.7.4 + '@opentelemetry/sdk-trace-node@2.6.1(@opentelemetry/api@1.9.1)': + dependencies: + '@opentelemetry/api': 1.9.1 + '@opentelemetry/context-async-hooks': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/core': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/sdk-trace-base': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/semantic-conventions@1.28.0': {} + '@opentelemetry/semantic-conventions@1.40.0': {} + '@oslojs/encoding@1.1.0': {} '@pagefind/darwin-arm64@1.5.2': @@ -10201,10 +10731,138 @@ snapshots: '@polka/url@1.0.0-next.29': {} + '@protobufjs/aspromise@1.1.2': {} + + '@protobufjs/base64@1.1.2': {} + + '@protobufjs/codegen@2.0.5': {} + + '@protobufjs/eventemitter@1.1.0': {} + + '@protobufjs/fetch@1.1.1': + dependencies: + '@protobufjs/aspromise': 1.1.2 + + '@protobufjs/float@1.0.2': {} + + '@protobufjs/inquire@1.1.2': {} + + '@protobufjs/path@1.1.2': {} + + '@protobufjs/pool@1.1.0': {} + + '@protobufjs/utf8@1.1.1': {} + '@quansync/fs@1.0.0': dependencies: quansync: 1.0.0 + '@redocly/ajv@8.11.2': + dependencies: + fast-deep-equal: 3.1.3 + json-schema-traverse: 1.0.0 + require-from-string: 2.0.2 + uri-js-replace: 1.0.1 + + '@redocly/ajv@8.18.1': + dependencies: + fast-deep-equal: 3.1.3 + fast-uri: 3.1.0 + json-schema-traverse: 1.0.0 + require-from-string: 2.0.2 + + '@redocly/cli-otel@0.3.1': + dependencies: + ulid: 2.4.0 + + '@redocly/cli@2.31.2(@opentelemetry/api@1.9.1)(core-js@3.49.0)': + dependencies: + '@opentelemetry/exporter-trace-otlp-http': 0.214.0(@opentelemetry/api@1.9.1) + '@opentelemetry/resources': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/sdk-trace-node': 2.6.1(@opentelemetry/api@1.9.1) + '@opentelemetry/semantic-conventions': 1.40.0 + '@redocly/cli-otel': 0.3.1 + '@redocly/openapi-core': 2.31.2 + '@redocly/respect-core': 2.31.2 + ajv: '@redocly/ajv@8.18.1' + ajv-formats: 3.0.1(@redocly/ajv@8.18.1) + colorette: 1.4.0 + cookie: 0.7.2 + dotenv: 16.4.7 + glob: 11.1.0 + handlebars: 4.7.9 + https-proxy-agent: 7.0.6(supports-color@10.2.2) + mobx: 6.15.3 + picomatch: 4.0.4 + pluralize: 8.0.0 + react: 19.2.5 + react-dom: 19.2.5(react@19.2.5) + redoc: 2.5.1(core-js@3.49.0)(mobx@6.15.3)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)(styled-components@6.4.1(react-dom@19.2.5(react@19.2.5))(react@19.2.5)) + semver: 7.7.4 + set-cookie-parser: 2.7.2 + simple-websocket: 9.1.0 + styled-components: 6.4.1(react-dom@19.2.5(react@19.2.5))(react@19.2.5) + ulid: 3.0.2 + undici: 6.24.0 + yargs: 17.0.1 + transitivePeerDependencies: + - '@opentelemetry/api' + - bufferutil + - core-js + - css-to-react-native + - encoding + - react-native + - supports-color + - utf-8-validate + + '@redocly/config@0.22.0': {} + + '@redocly/config@0.48.2': + dependencies: + json-schema-to-ts: 2.7.2 + + '@redocly/openapi-core@1.34.14': + dependencies: + '@redocly/ajv': 8.11.2 + '@redocly/config': 0.22.0 + colorette: 1.4.0 + https-proxy-agent: 7.0.6(supports-color@10.2.2) + js-levenshtein: 1.1.6 + js-yaml: 4.1.1 + minimatch: 5.1.9 + pluralize: 8.0.0 + yaml-ast-parser: 0.0.43 + transitivePeerDependencies: + - supports-color + + '@redocly/openapi-core@2.31.2': + dependencies: + '@redocly/ajv': 8.18.1 + '@redocly/config': 0.48.2 + ajv: '@redocly/ajv@8.18.1' + ajv-formats: 3.0.1(@redocly/ajv@8.18.1) + colorette: 1.4.0 + js-levenshtein: 1.1.6 + js-yaml: 4.1.1 + picomatch: 4.0.4 + pluralize: 8.0.0 + yaml-ast-parser: 0.0.43 + + '@redocly/respect-core@2.31.2': + dependencies: + '@faker-js/faker': 7.6.0 + '@noble/hashes': 1.8.0 + '@redocly/ajv': 8.18.1 + '@redocly/openapi-core': 2.31.2 + ajv: '@redocly/ajv@8.18.1' + better-ajv-errors: 2.0.3(@redocly/ajv@8.18.1) + colorette: 2.0.20 + json-pointer: 0.6.2 + jsonpath-rfc9535: 1.3.0 + openapi-sampler: 1.7.3 + outdent: 0.8.0 + picomatch: 4.0.4 + '@replit/codemirror-css-color-picker@6.3.0(@codemirror/language@6.12.3)(@codemirror/state@6.6.0)(@codemirror/view@6.41.0)': dependencies: '@codemirror/language': 6.12.3 @@ -10886,6 +11544,8 @@ snapshots: '@types/js-yaml@4.0.9': {} + '@types/json-schema@7.0.15': {} + '@types/mdast@4.0.4': dependencies: '@types/unist': 3.0.3 @@ -11582,6 +12242,10 @@ snapshots: dependencies: ajv: 8.18.0 + ajv-formats@3.0.1(@redocly/ajv@8.18.1): + optionalDependencies: + ajv: '@redocly/ajv@8.18.1' + ajv-formats@3.0.1(ajv@8.18.0): optionalDependencies: ajv: 8.18.0 @@ -11929,6 +12593,15 @@ snapshots: jsonpointer: 5.0.1 leven: 3.1.0 + better-ajv-errors@2.0.3(@redocly/ajv@8.18.1): + dependencies: + '@babel/code-frame': 7.29.0 + '@humanwhocodes/momoa': 2.0.4 + ajv: '@redocly/ajv@8.18.1' + chalk: 4.1.2 + jsonpointer: 5.0.1 + leven: 3.1.0 + binary-extensions@2.3.0: {} bindings@1.5.0: @@ -12037,6 +12710,8 @@ snapshots: call-bind-apply-helpers: 1.0.2 get-intrinsic: 1.3.0 + call-me-maybe@1.0.2: {} + callsite@1.0.0: {} camel-case@4.1.2: @@ -12103,6 +12778,8 @@ snapshots: cjs-module-lexer@1.4.3: {} + classnames@2.5.1: {} + clean-css@5.3.3: dependencies: source-map: 0.6.1 @@ -12131,6 +12808,12 @@ snapshots: cli-width@3.0.0: {} + cliui@7.0.4: + dependencies: + string-width: 4.2.3 + strip-ansi: 6.0.1 + wrap-ansi: 7.0.0 + cliui@8.0.1: dependencies: string-width: 4.2.3 @@ -12164,6 +12847,8 @@ snapshots: color-convert: 3.1.3 color-string: 2.1.4 + colorette@1.4.0: {} + colorette@2.0.20: {} colors@1.4.0: {} @@ -12234,6 +12919,8 @@ snapshots: graceful-fs: 4.2.11 p-event: 6.0.1 + core-js@3.49.0: {} + core-util-is@1.0.3: {} cpy@11.1.0: @@ -12347,6 +13034,8 @@ snapshots: dependencies: callsite: 1.0.0 + decko@1.2.0: {} + decode-named-character-reference@1.3.0: dependencies: character-entities: 2.0.2 @@ -12505,6 +13194,8 @@ snapshots: dependencies: type-fest: 4.41.0 + dotenv@16.4.7: {} + dotenv@16.6.1: {} dotenv@17.3.1: {} @@ -12668,6 +13359,8 @@ snapshots: is-date-object: 1.1.0 is-symbol: 1.1.1 + es6-promise@3.3.1: {} + esast-util-from-estree@2.0.0: dependencies: '@types/estree-jsx': 1.0.5 @@ -13076,6 +13769,8 @@ snapshots: dependencies: is-callable: 1.2.7 + foreach@2.0.6: {} + foreground-child@3.3.1: dependencies: cross-spawn: 7.0.6 @@ -13241,6 +13936,15 @@ snapshots: ufo: 1.6.3 uncrypto: 0.1.3 + handlebars@4.7.9: + dependencies: + minimist: 1.2.8 + neo-async: 2.6.2 + source-map: 0.6.1 + wordwrap: 1.0.0 + optionalDependencies: + uglify-js: 3.19.3 + has-bigints@1.1.0: {} has-flag@4.0.0: {} @@ -13562,6 +14266,8 @@ snapshots: http-shutdown@1.2.2: {} + http2-client@1.3.5: {} + https-proxy-agent@7.0.6(supports-color@10.2.2): dependencies: agent-base: 7.1.4 @@ -13975,6 +14681,8 @@ snapshots: dependencies: jpeg-js: 0.4.4 + js-levenshtein@1.1.6: {} + js-tokens@4.0.0: {} js-yaml@4.1.1: @@ -13983,10 +14691,20 @@ snapshots: jsesc@3.1.0: {} + json-pointer@0.6.2: + dependencies: + foreach: 2.0.6 + json-schema-ref-resolver@3.0.0: dependencies: dequal: 2.0.3 + json-schema-to-ts@2.7.2: + dependencies: + '@babel/runtime': 7.29.2 + '@types/json-schema': 7.0.15 + ts-algebra: 1.2.2 + json-schema-traverse@1.0.0: {} json-schema@0.4.0: {} @@ -13999,6 +14717,8 @@ snapshots: jsonc-parser@3.3.1: {} + jsonpath-rfc9535@1.3.0: {} + jsonpointer@5.0.1: {} jsonwebtoken@9.0.3: @@ -14202,8 +14922,14 @@ snapshots: safe-stable-stringify: 2.5.0 triple-beam: 1.4.1 + long@5.3.2: {} + longest-streak@3.1.0: {} + loose-envify@1.4.0: + dependencies: + js-tokens: 4.0.0 + lower-case@2.0.2: dependencies: tslib: 2.8.1 @@ -14222,6 +14948,8 @@ snapshots: dependencies: yallist: 3.1.1 + lunr@2.3.9: {} + luxon@3.7.2: {} macos-release@3.4.0: {} @@ -14250,6 +14978,8 @@ snapshots: map-obj@5.0.2: {} + mark.js@8.11.1: {} + markdown-extensions@2.0.0: {} markdown-table@3.0.4: {} @@ -14273,6 +15003,8 @@ snapshots: marked@17.0.6: {} + marked@4.3.0: {} + math-intrinsics@1.1.0: {} maxstache-stream@1.0.4: @@ -14808,6 +15540,24 @@ snapshots: pkg-types: 1.3.1 ufo: 1.6.3 + mobx-react-lite@4.1.1(mobx@6.15.3)(react-dom@19.2.5(react@19.2.5))(react@19.2.5): + dependencies: + mobx: 6.15.3 + react: 19.2.5 + use-sync-external-store: 1.6.0(react@19.2.5) + optionalDependencies: + react-dom: 19.2.5(react@19.2.5) + + mobx-react@9.2.0(mobx@6.15.3)(react-dom@19.2.5(react@19.2.5))(react@19.2.5): + dependencies: + mobx: 6.15.3 + mobx-react-lite: 4.1.1(mobx@6.15.3)(react-dom@19.2.5(react@19.2.5))(react@19.2.5) + react: 19.2.5 + optionalDependencies: + react-dom: 19.2.5(react@19.2.5) + + mobx@6.15.3: {} + modern-tar@0.7.5: {} module-definition@6.0.1: @@ -14886,6 +15636,8 @@ snapshots: negotiator@1.0.0: {} + neo-async@2.6.2: {} + neotraverse@0.6.18: {} netlify-cli@25.3.0(@types/node@25.6.0)(picomatch@4.0.4)(rollup@4.60.1): @@ -15049,6 +15801,10 @@ snapshots: object.entries: 1.1.9 semver: 6.3.1 + node-fetch-h2@2.3.0: + dependencies: + http2-client: 1.3.5 + node-fetch-native@1.6.7: {} node-fetch@2.7.0: @@ -15067,6 +15823,10 @@ snapshots: node-mock-http@1.0.4: {} + node-readfiles@0.2.0: + dependencies: + es6-promise: 3.3.1 + node-releases@2.0.37: {} node-source-walk@7.0.1: @@ -15120,6 +15880,39 @@ snapshots: dependencies: boolbase: 1.0.0 + oas-kit-common@1.0.8: + dependencies: + fast-safe-stringify: 2.1.1 + + oas-linter@3.2.2: + dependencies: + '@exodus/schemasafe': 1.3.0 + should: 13.2.3 + yaml: 1.10.3 + + oas-resolver@2.5.6: + dependencies: + node-fetch-h2: 2.3.0 + oas-kit-common: 1.0.8 + reftools: 1.1.9 + yaml: 1.10.3 + yargs: 17.7.2 + + oas-schema-walker@1.1.5: {} + + oas-validator@5.0.8: + dependencies: + call-me-maybe: 1.0.2 + oas-kit-common: 1.0.8 + oas-linter: 3.2.2 + oas-resolver: 2.5.6 + oas-schema-walker: 1.1.5 + reftools: 1.1.9 + should: 13.2.3 + yaml: 1.10.3 + + object-assign@4.1.1: {} + object-inspect@1.13.4: {} object-keys@1.1.1: {} @@ -15218,6 +16011,12 @@ snapshots: powershell-utils: 0.1.0 wsl-utils: 0.3.1 + openapi-sampler@1.7.3: + dependencies: + '@types/json-schema': 7.0.15 + fast-xml-parser: 5.6.0 + json-pointer: 0.6.2 + ora@5.4.1: dependencies: bl: 4.1.0 @@ -15235,6 +16034,8 @@ snapshots: macos-release: 3.4.0 windows-release: 6.1.0 + outdent@0.8.0: {} + own-keys@1.0.1: dependencies: get-intrinsic: 1.3.0 @@ -15404,6 +16205,8 @@ snapshots: perfect-debounce@2.1.0: {} + perfect-scrollbar@1.5.6: {} + pg-cloudflare@1.3.0: optional: true @@ -15483,6 +16286,12 @@ snapshots: exsolve: 1.0.8 pathe: 2.0.3 + pluralize@8.0.0: {} + + polished@4.3.1: + dependencies: + '@babel/runtime': 7.29.2 + possible-typed-array-names@1.1.0: {} postcss-nested@6.2.0(postcss@8.5.10): @@ -15586,10 +16395,31 @@ snapshots: process@0.11.10: {} + prop-types@15.8.1: + dependencies: + loose-envify: 1.4.0 + object-assign: 4.1.1 + react-is: 16.13.1 + property-information@7.1.0: {} proto-list@1.2.4: {} + protobufjs@7.6.0: + dependencies: + '@protobufjs/aspromise': 1.1.2 + '@protobufjs/base64': 1.1.2 + '@protobufjs/codegen': 2.0.5 + '@protobufjs/eventemitter': 1.1.0 + '@protobufjs/fetch': 1.1.1 + '@protobufjs/float': 1.0.2 + '@protobufjs/inquire': 1.1.2 + '@protobufjs/path': 1.1.2 + '@protobufjs/pool': 1.1.0 + '@protobufjs/utf8': 1.1.1 + '@types/node': 25.6.0 + long: 5.3.2 + proxy-addr@2.0.7: dependencies: forwarded: 0.2.0 @@ -15646,6 +16476,10 @@ snapshots: random-bytes@1.0.0: {} + randombytes@2.1.0: + dependencies: + safe-buffer: 5.2.1 + range-parser@1.2.1: {} raw-body@3.0.1: @@ -15667,8 +16501,16 @@ snapshots: react: 19.2.5 scheduler: 0.27.0 + react-is@16.13.1: {} + react-refresh@0.18.0: {} + react-tabs@6.1.1(react@19.2.5): + dependencies: + clsx: 2.1.1 + prop-types: 15.8.1 + react: 19.2.5 + react@19.2.5: {} read-package-up@11.0.0: @@ -15766,6 +16608,39 @@ snapshots: unified: 11.0.5 vfile: 6.0.3 + redoc@2.5.1(core-js@3.49.0)(mobx@6.15.3)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)(styled-components@6.4.1(react-dom@19.2.5(react@19.2.5))(react@19.2.5)): + dependencies: + '@redocly/openapi-core': 1.34.14 + classnames: 2.5.1 + core-js: 3.49.0 + decko: 1.2.0 + dompurify: 3.2.7 + eventemitter3: 5.0.4 + json-pointer: 0.6.2 + lunr: 2.3.9 + mark.js: 8.11.1 + marked: 4.3.0 + mobx: 6.15.3 + mobx-react: 9.2.0(mobx@6.15.3)(react-dom@19.2.5(react@19.2.5))(react@19.2.5) + openapi-sampler: 1.7.3 + path-browserify: 1.0.1 + perfect-scrollbar: 1.5.6 + polished: 4.3.1 + prismjs: 1.30.0 + prop-types: 15.8.1 + react: 19.2.5 + react-dom: 19.2.5(react@19.2.5) + react-tabs: 6.1.1(react@19.2.5) + slugify: 1.4.7 + stickyfill: 1.1.1 + styled-components: 6.4.1(react-dom@19.2.5(react@19.2.5))(react@19.2.5) + swagger2openapi: 7.0.8 + url-template: 2.0.8 + transitivePeerDependencies: + - encoding + - react-native + - supports-color + reflect.getprototypeof@1.0.10: dependencies: call-bind: 1.0.9 @@ -15777,6 +16652,8 @@ snapshots: get-proto: 1.0.1 which-builtin-type: 1.2.1 + reftools@1.1.9: {} + regex-recursion@6.0.2: dependencies: regex-utilities: 2.3.0 @@ -16266,6 +17143,32 @@ snapshots: '@shikijs/vscode-textmate': 10.0.2 '@types/hast': 3.0.4 + should-equal@2.0.0: + dependencies: + should-type: 1.4.0 + + should-format@3.0.3: + dependencies: + should-type: 1.4.0 + should-type-adaptors: 1.1.0 + + should-type-adaptors@1.1.0: + dependencies: + should-type: 1.4.0 + should-util: 1.0.1 + + should-type@1.4.0: {} + + should-util@1.0.1: {} + + should@13.2.3: + dependencies: + should-equal: 2.0.0 + should-format: 3.0.3 + should-type: 1.4.0 + should-type-adaptors: 1.1.0 + should-util: 1.0.1 + side-channel-list@1.0.1: dependencies: es-errors: 1.3.0 @@ -16300,6 +17203,18 @@ snapshots: simple-git-hooks@2.13.1: {} + simple-websocket@9.1.0: + dependencies: + debug: 4.4.3(supports-color@10.2.2) + queue-microtask: 1.2.3 + randombytes: 2.1.0 + readable-stream: 3.6.2 + ws: 7.5.10 + transitivePeerDependencies: + - bufferutil + - supports-color + - utf-8-validate + sirv@3.0.2: dependencies: '@polka/url': 1.0.0-next.29 @@ -16324,6 +17239,8 @@ snapshots: ansi-styles: 6.2.3 is-fullwidth-code-point: 5.1.0 + slugify@1.4.7: {} + smartypants@0.2.2: {} smol-toml@1.6.1: {} @@ -16522,6 +17439,8 @@ snapshots: std-env@4.1.0: {} + stickyfill@1.1.1: {} + stop-iteration-iterator@1.1.0: dependencies: es-errors: 1.3.0 @@ -16634,6 +17553,17 @@ snapshots: dependencies: inline-style-parser: 0.2.7 + styled-components@6.4.1(react-dom@19.2.5(react@19.2.5))(react@19.2.5): + dependencies: + '@emotion/is-prop-valid': 1.4.0 + csstype: 3.2.3 + react: 19.2.5 + stylis: 4.3.6 + optionalDependencies: + react-dom: 19.2.5(react@19.2.5) + + stylis@4.3.6: {} + suf-log@2.5.3: dependencies: s.color: 0.0.15 @@ -16672,6 +17602,22 @@ snapshots: picocolors: 1.1.1 sax: 1.6.0 + swagger2openapi@7.0.8: + dependencies: + call-me-maybe: 1.0.2 + node-fetch: 2.7.0 + node-fetch-h2: 2.3.0 + node-readfiles: 0.2.0 + oas-kit-common: 1.0.8 + oas-resolver: 2.5.6 + oas-schema-walker: 1.1.5 + oas-validator: 5.0.8 + reftools: 1.1.9 + yaml: 1.10.3 + yargs: 17.7.2 + transitivePeerDependencies: + - encoding + swrv@1.2.0(vue@3.5.33(typescript@6.0.3)): dependencies: vue: 3.5.33(typescript@6.0.3) @@ -16801,6 +17747,8 @@ snapshots: string-byte-length: 3.0.1 string-byte-slice: 3.0.1 + ts-algebra@1.2.2: {} + ts-api-utils@2.5.0(typescript@5.9.3): dependencies: typescript: 5.9.3 @@ -16900,10 +17848,15 @@ snapshots: ufo@1.6.3: {} + uglify-js@3.19.3: + optional: true + uid-safe@2.1.5: dependencies: random-bytes: 1.0.0 + ulid@2.4.0: {} + ulid@3.0.1: {} ulid@3.0.2: {} @@ -16936,6 +17889,8 @@ snapshots: undici-types@7.19.2: {} + undici@6.24.0: {} + unhead@2.1.13: dependencies: hookable: 6.1.1 @@ -17145,10 +18100,18 @@ snapshots: uqr@0.1.3: {} + uri-js-replace@1.0.1: {} + + url-template@2.0.8: {} + urlpattern-polyfill@10.1.0: {} urlpattern-polyfill@8.0.2: {} + use-sync-external-store@1.6.0(react@19.2.5): + dependencies: + react: 19.2.5 + util-deprecate@1.0.2: {} uuid@11.1.0: {} @@ -17509,6 +18472,8 @@ snapshots: triple-beam: 1.4.1 winston-transport: 4.9.0 + wordwrap@1.0.0: {} + wrap-ansi@10.0.0: dependencies: ansi-styles: 6.2.3 @@ -17540,6 +18505,8 @@ snapshots: imurmurhash: 0.1.4 signal-exit: 4.1.0 + ws@7.5.10: {} + ws@8.19.0: {} wsl-utils@0.1.0: @@ -17568,6 +18535,8 @@ snapshots: yallist@5.0.0: {} + yaml-ast-parser@0.0.43: {} + yaml-language-server@1.20.0: dependencies: '@vscode/l10n': 0.0.18 @@ -17582,14 +18551,28 @@ snapshots: vscode-uri: 3.1.0 yaml: 2.7.1 + yaml@1.10.3: {} + yaml@2.7.1: {} yaml@2.8.3: {} + yargs-parser@20.2.9: {} + yargs-parser@21.1.1: {} yargs-parser@22.0.0: {} + yargs@17.0.1: + dependencies: + cliui: 7.0.4 + escalade: 3.2.0 + get-caller-file: 2.0.5 + require-directory: 2.1.1 + string-width: 4.2.3 + y18n: 5.0.8 + yargs-parser: 20.2.9 + yargs@17.7.2: dependencies: cliui: 8.0.1 diff --git a/public/agentkit/apis.md b/public/agentkit/apis.md new file mode 100644 index 000000000..292ddf6e3 --- /dev/null +++ b/public/agentkit/apis.md @@ -0,0 +1,2782 @@ +# AgentKit APIs + +- **OpenAPI Version:** `3.1.1` +- **API Version:** `1.0.0` + +The AgentKit API enables you to manage connected accounts for third-party integrations, execute tools on behalf of users, and handle OAuth connections to external services like Google, Notion, Slack, and other applications. + +## Quickstart + +The Scalekit API uses OAuth 2.0 Client Credentials for authentication. + +Copy your API credentials from the Scalekit dashboard's API Config section and set them as environment variables. + +```sh +SCALEKIT_ENVIRONMENT_URL='' +SCALEKIT_CLIENT_ID='' +SCALEKIT_CLIENT_SECRET='' +``` + +Getting an access token + +1. Get your credentials from the [Scalekit Dashboard](https://app.scalekit.com) +2. Request an access token: + +```sh +curl https:///oauth/token \ + -X POST \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'client_id={client_id}' \ + -d 'client_secret={client_secret}' \ + -d 'grant_type=client_credentials' +``` + +3. Use the access token in API requests: + +```sh +curl https:///api/v1/connected_accounts \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {access_token}' +``` + +## Servers + +- **URL:** `https://$SCALEKIT_ENVIRONMENT_URL` + +## Operations + +### List connected accounts + +- **Method:** `GET` +- **Path:** `/api/v1/connected_accounts` +- **Tags:** Connected Accounts + +Retrieves a paginated list of connected accounts for third-party integrations. Filter by organization, user, connector type, provider, or identifier. Returns OAuth tokens, API keys, and connection status for each account. Use pagination tokens to navigate through large result sets. + +#### Responses + +##### Status: 200 Successfully retrieved the list of connected accounts with their authentication details and status + +###### Content-Type: application/json + +- **`connected_accounts`** + + `array` — List of connected accounts matching the filter criteria. Excludes sensitive authorization details for security. + + **Items:** + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Authorization mechanism type. + + - **`connection_id`** + + `string` — Parent connection configuration reference. + + - **`connector`** + + `string` — Connector identifier. + + - **`id`** + + `string` — Unique connected account identifier. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. + + - **`last_used_at`** + + `string`, format: `date-time` — Last usage timestamp. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft'). + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current connection status. + + - **`token_expires_at`** + + `string`, format: `date-time` — Token expiration timestamp. + + - **`updated_at`** + + `string`, format: `date-time` — Last modification timestamp. + +- **`next_page_token`** + + `string` — Pagination token for retrieving the next page. Empty if this is the last page. Pass this value to page\_token in the next request. + +- **`prev_page_token`** + + `string` — Pagination token for retrieving the previous page. Empty if this is the first page. Pass this value to page\_token to go back. + +- **`total_size`** + + `integer`, format: `int64` — Total count of connected accounts matching the filter criteria across all pages. Use for calculating pagination. + +**Example:** + +```json +{ + "connected_accounts": [ + { + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } + ], + "next_page_token": "eyJvZmZzZXQiOjIwfQ==", + "prev_page_token": "eyJvZmZzZXQiOjB9", + "total_size": 100 +} +``` + +##### Status: 400 Invalid request - occurs when query parameters are malformed or validation fails + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Update connected account credentials + +- **Method:** `PUT` +- **Path:** `/api/v1/connected_accounts` +- **Tags:** Connected Accounts + +Updates authentication credentials and configuration for an existing connected account. Modify OAuth tokens, refresh tokens, access scopes, or API configuration settings. Specify the account by ID, or by combination of organization/user, connector, and identifier. Returns the updated account with new token expiry and status information. + +#### Request Body + +##### Content-Type: application/json + +- **`connected_account`** + + `object` — Details of the connected account to update + + - **`api_config`** + + `object` — Updated JSON configuration for API-specific settings. Merges with existing configuration - only provided fields are modified. + + - **`authorization_details`** + + `object` — Updated authentication credentials. Provide new OAuth tokens (e.g., after refresh) or updated static auth details. Only included fields will be modified. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +- **`connector`** + + `string` — Connector identifier + +- **`id`** + + `string` — Unique identifier for the connected account to update + +- **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +- **`organization_id`** + + `string` — Organization ID for the connector + +- **`user_id`** + + `string` — User ID for the connector + +**Example:** + +```json +{ + "connected_account": { + "authorization_details": { + "oauth_token": { + "access_token": "...", + "refresh_token": "...", + "scopes": [ + "read", + "write" + ] + } + }, + "authorization_type": "OAUTH2" + }, + "connector": "notion", + "id": "ca_123", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "user_id": "user_121312434123312" +} +``` + +#### Responses + +##### Status: 200 Connected account updated successfully with new credentials or configuration + +###### Content-Type: application/json + +- **`connected_account`** + + `object` — The updated connected account with refreshed credentials, new token expiry, and modified configuration settings. + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. + + - **`authorization_details`** + + `object` — Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. + + - **`connection_id`** + + `string` — Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. + + - **`connector`** + + `string` — Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to. + + - **`id`** + + `string` — Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca\_'. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier. + + - **`last_used_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection. + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. + + - **`token_expires_at`** + + `string`, format: `date-time` — Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. + +**Example:** + +```json +{ + "connected_account": { + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": null, + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } +} +``` + +##### Status: 400 Invalid request - missing required fields, invalid authorization details, or validation failed + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 404 Connected account not found - the specified account does not exist + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Create a connected account + +- **Method:** `POST` +- **Path:** `/api/v1/connected_accounts` +- **Tags:** Connected Accounts + +Creates a new connected account with OAuth tokens or API credentials for third-party service integration. Supply authorization details including access tokens, refresh tokens, scopes, and optional API configuration. The account can be scoped to an organization or user. Returns the created account with its unique identifier and authentication status. + +#### Request Body + +##### Content-Type: application/json + +- **`connected_account`** + + `object` — Details of the connected account to create + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom API endpoints, timeouts, or feature flags. + + - **`authorization_details`** + + `object` — Optional authentication credentials for the connected account. Include OAuth tokens (access\_token, refresh\_token, scopes) or static auth details (API keys, bearer tokens). Can be provided later via update. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +- **`connector`** + + `string` — Connector identifier + +- **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +- **`organization_id`** + + `string` — Organization ID for the connector + +- **`user_id`** + + `string` — User ID for the connector + +**Example:** + +```json +{ + "connected_account": { + "authorization_details": { + "oauth_token": { + "access_token": "...", + "refresh_token": "...", + "scopes": [ + "read", + "write" + ] + } + }, + "authorization_type": "OAUTH2" + }, + "connector": "notion", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "user_id": "user_121312434123312" +} +``` + +#### Responses + +##### Status: 201 Connected account created successfully with authentication credentials stored securely + +###### Content-Type: application/json + +- **`connected_account`** + + `object` — The newly created connected account with its unique identifier, status, and complete authorization details including access tokens. + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. + + - **`authorization_details`** + + `object` — Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. + + - **`connection_id`** + + `string` — Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. + + - **`connector`** + + `string` — Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to. + + - **`id`** + + `string` — Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca\_'. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier. + + - **`last_used_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection. + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. + + - **`token_expires_at`** + + `string`, format: `date-time` — Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. + +**Example:** + +```json +{ + "connected_account": { + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": null, + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } +} +``` + +##### Status: 400 Invalid request - missing required fields, invalid authorization details, or validation failed + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 409 Conflict - connected account with the same identifier already exists + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Get connected account details + +- **Method:** `GET` +- **Path:** `/api/v1/connected_accounts/auth` +- **Tags:** Connected Accounts + +Retrieves complete authentication details for a connected account including OAuth tokens, refresh tokens, scopes, and API configuration. Query by account ID or by combination of organization/user, connector, and identifier. Returns sensitive credential information - use appropriate access controls. + +#### Responses + +##### Status: 200 Successfully retrieved connected account with full authentication details + +###### Content-Type: application/json + +- **`connected_account`** + + `object` — The connected account with complete details including sensitive authorization credentials (access tokens, refresh tokens, scopes). Handle with appropriate access controls. + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. + + - **`authorization_details`** + + `object` — Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. + + - **`connection_id`** + + `string` — Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. + + - **`connector`** + + `string` — Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to. + + - **`id`** + + `string` — Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca\_'. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier. + + - **`last_used_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection. + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. + + - **`token_expires_at`** + + `string`, format: `date-time` — Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. + +**Example:** + +```json +{ + "connected_account": { + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": null, + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } +} +``` + +##### Status: 400 Invalid request - missing required query parameters + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 404 Connected account not found - no account matches the specified criteria + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Generate authentication magic link + +- **Method:** `POST` +- **Path:** `/api/v1/connected_accounts/magic_link` +- **Tags:** Connected Accounts + +Creates a time-limited magic link for connecting or re-authorizing a third-party account. The link directs users to the OAuth authorization flow for the specified connector. Returns the generated link URL and expiration timestamp. Links typically expire after a short duration for security. + +#### Request Body + +##### Content-Type: application/json + +- **`connector`** + + `string` — Connector identifier + +- **`id`** + + `string` — Unique identifier for the connected account + +- **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +- **`organization_id`** + + `string` — Organization ID for the connector + +- **`state`** + + `string` — Optional opaque state value. State added to the user verify redirect URL query params to validate the user verification + +- **`user_id`** + + `string` — User ID for the connector + +- **`user_verify_url`** + + `string` — B2B app's user verify redirect URL + +**Example:** + +```json +{ + "connector": "notion", + "id": "ca_123", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "state": "QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY=", + "user_id": "user_121312434123312", + "user_verify_url": "https://app.yourapp.com/user/verify/callback" +} +``` + +#### Responses + +##### Status: 200 Magic link generated successfully with authorization URL and expiry time + +###### Content-Type: application/json + +- **`expiry`** + + `string`, format: `date-time` — Expiry timestamp for the authentication link + +- **`link`** + + `string` — Authentication link for the connector + +**Example:** + +```json +{ + "expiry": "2024-03-20T15:04:05Z", + "link": "https://notion.com/oauth/authorize?client_id=..." +} +``` + +##### Status: 400 Invalid request - missing required parameters or invalid connector + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Verify connected account user + +- **Method:** `POST` +- **Path:** `/api/v1/connected_accounts/user/verify` +- **Tags:** Connected Accounts + +Confirms the user assertion and activates the connected account after the user completes third-party OAuth. Called by the B2B app server with auth\_request\_id and identifier. Validates that the asserted identifier matches the one stored on the auth request and promotes pending tokens to live. + +#### Request Body + +##### Content-Type: application/json + +- **`auth_request_id` (required)** + + `string` — Auth request ID as base64url-encoded opaque token from the user verify redirect URL query params + +- **`identifier` (required)** + + `string` — Current logged in user's connected account identifier + +**Example:** + +```json +{ + "auth_request_id": "QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY=", + "identifier": "user@example.com" +} +``` + +#### Responses + +##### Status: 200 Verification successful; connected account is now ACTIVE + +###### Content-Type: application/json + +- **`post_user_verify_redirect_url`** + + `string` — URL to redirect the user to after successful verification + +**Example:** + +```json +{ + "post_user_verify_redirect_url": "https://env1.example.com/connect/success" +} +``` + +##### Status: 400 Invalid request - missing or malformed fields + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Unauthorized - invalid or missing access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 403 Forbidden - identifier mismatch + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 404 Not found - no pending flow for the given auth\_request\_id or already consumed + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Delete a connected account + +- **Method:** `POST` +- **Path:** `/api/v1/connected_accounts:delete` +- **Tags:** Connected Accounts + +Permanently removes a connected account and revokes all associated authentication credentials. Identify the account by ID, or by combination of organization/user, connector, and identifier. This action cannot be undone. All OAuth tokens and API keys for this account will be invalidated. + +#### Request Body + +##### Content-Type: application/json + +- **`connector`** + + `string` — Connector identifier + +- **`id`** + + `string` — Unique identifier for the connected account to delete + +- **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +- **`organization_id`** + + `string` — Organization ID for the connector + +- **`user_id`** + + `string` — User ID for the connector + +**Example:** + +```json +{ + "connector": "notion", + "id": "ca_123", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "user_id": "user_121312434123312" +} +``` + +#### Responses + +##### Status: 200 Connected account deleted successfully and all credentials revoked + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 400 Invalid request - malformed parameters or validation failed + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 404 Connected account not found - the specified account does not exist + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Search connected accounts + +- **Method:** `GET` +- **Path:** `/api/v1/connected_accounts:search` +- **Tags:** Connected Accounts + +Search for connected accounts in your environment using a text query that matches against identifiers, providers, or connectors. The search performs case-insensitive matching across account details. Returns paginated results with account status and authentication type information. + +#### Responses + +##### Status: 200 Successfully retrieved matching connected accounts with pagination support + +###### Content-Type: application/json + +- **`connected_accounts`** + + `array` — List of connected accounts matching the search query. Excludes sensitive authorization details. + + **Items:** + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Authorization mechanism type. + + - **`connection_id`** + + `string` — Parent connection configuration reference. + + - **`connector`** + + `string` — Connector identifier. + + - **`id`** + + `string` — Unique connected account identifier. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. + + - **`last_used_at`** + + `string`, format: `date-time` — Last usage timestamp. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft'). + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current connection status. + + - **`token_expires_at`** + + `string`, format: `date-time` — Token expiration timestamp. + + - **`updated_at`** + + `string`, format: `date-time` — Last modification timestamp. + +- **`next_page_token`** + + `string` — Pagination token for the next page. Empty if this is the last page. + +- **`prev_page_token`** + + `string` — Pagination token for the previous page. Empty if this is the first page. + +- **`total_size`** + + `integer`, format: `int64` — Total count of accounts matching the search query across all pages. + +**Example:** + +```json +{ + "connected_accounts": [ + { + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } + ], + "next_page_token": "eyJvZmZzZXQiOjMwfQ==", + "prev_page_token": "eyJvZmZzZXQiOjB9", + "total_size": 100 +} +``` + +##### Status: 400 Invalid request - query parameter is too short (minimum 3 characters) or validation failed + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Execute a tool using a connected account + +- **Method:** `POST` +- **Path:** `/api/v1/execute_tool` +- **Tags:** Connected Accounts + +Executes a tool action using authentication credentials from a connected account. Specify the tool by name and provide required parameters as JSON. The connected account can be identified by ID, or by combination of organization/user, connector, and identifier. Returns the execution result data and a unique execution ID for tracking. Use this endpoint to perform actions like sending emails, creating calendar events, or managing resources in external services. + +#### Request Body + +##### Content-Type: application/json + +- **`connected_account_id`** + + `string` — Optional. The unique ID of the connected account. Use this to directly identify the connected account instead of using identifier + connector combination. + +- **`connector`** + + `string` — Optional. The name of the connector/provider (e.g., 'Google Workspace', 'Slack', 'Notion'). Use this in combination with identifier to identify the connected account. + +- **`identifier`** + + `string` — Optional. The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). Use this in combination with connector to identify the connected account. + +- **`organization_id`** + + `string` — Optional. The organization ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple organizations. + +- **`params`** + + `object` — JSON object containing the parameters required for tool execution. The structure depends on the specific tool being executed. + +- **`tool_name`** + + `string` — Name of the tool to execute + +- **`user_id`** + + `string` — Optional. The user ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple users. + +**Example:** + +```json +{ + "connected_account_id": "ca_123", + "connector": "Google Workspace", + "identifier": "user@example.com", + "organization_id": "org_123", + "params": { + "body": "Hello World", + "subject": "Hello", + "to": "user@example.com" + }, + "tool_name": "send_email", + "user_id": "user_123" +} +``` + +#### Responses + +##### Status: 200 Tool executed successfully with result data and execution ID + +###### Content-Type: application/json + +- **`data`** + + `object` — Free-flowing JSON parameters for the tool execution + +- **`execution_id`** + + `string` — Unique identifier for the tool execution + +**Example:** + +```json +{ + "data": { + "body": "Hello World", + "subject": "Hello", + "to": "user@example.com" + }, + "execution_id": "123456789" +} +``` + +##### Status: 400 Invalid request - occurs when tool name is missing, parameters are malformed, or tool definition validation fails + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 404 Tool or connected account not found - occurs when the specified tool name or connected account does not exist + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 500 Tool execution failed - occurs when the external service returns an error or the tool encounters a runtime exception + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +## Webhooks + +### Connected Account Created + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.created` + +Triggered when a new connected account is created + +### Connected Account Updated + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.updated` + +Triggered when a connected account is updated + +### Connected Account Deleted + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.deleted` + +Triggered when a connected account is deleted + +### Connected Account Magic Link Generated + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.magic_link_generated` + +Triggered when a magic link is generated for OAuth flow + +### Connected Account OAuth Tokens Fetched + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.oauth_tokens_fetched` + +Triggered when OAuth tokens are successfully fetched + +### Connected Account Token Refresh Succeeded + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.token_refresh_succeeded` + +Triggered when token refresh succeeds + +### Connected Account Token Refresh Failed + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.token_refresh_failed` + +Triggered when token refresh fails + +### Connected Account OAuth Succeeded + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.oauth_succeeded` + +Triggered when OAuth authentication succeeds + +## Schemas + +### Type of authentication mechanism used for the connected account + +- **Type:**`string` + +* OAUTH: OAuth 2.0 authorization with access and refresh tokens +* API\_KEY: Static API key authentication +* BASIC\_AUTH: HTTP Basic Authentication (username/password) +* BEARER\_TOKEN: Bearer token authentication +* CUSTOM: Custom authentication mechanism +* BASIC: Basic authentication (alias) + +**Example:** + +### Status of a connected account indicating its current state + +- **Type:**`string` + +* ACTIVE: Account is connected and credentials are valid +* EXPIRED: Access token has expired and needs refresh +* PENDING\_AUTH: Account awaiting user authorization (re-auth initiated) +* PENDING\_VERIFICATION: OAuth complete; awaiting user identity verification before activation + +**Example:** + +### Connected account summary for list operations - excludes sensitive authorization details + +- **Type:**`object` + +* **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Authorization mechanism type. + +* **`connection_id`** + + `string` — Parent connection configuration reference. + +* **`connector`** + + `string` — Connector identifier. + +* **`id`** + + `string` — Unique connected account identifier. + +* **`identifier`** + + `string` — The unique identifier for this account in the third-party service. + +* **`last_used_at`** + + `string`, format: `date-time` — Last usage timestamp. + +* **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft'). + +* **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current connection status. + +* **`token_expires_at`** + + `string`, format: `date-time` — Token expiration timestamp. + +* **`updated_at`** + + `string`, format: `date-time` — Last modification timestamp. + +**Example:** + +```json +{ + "authorization_type": "OAUTH", + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": "ACTIVE", + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" +} +``` + +### connected\_accountsListConnectedAccountsResponse + +- **Type:**`object` + +* **`connected_accounts`** + + `array` — List of connected accounts matching the filter criteria. Excludes sensitive authorization details for security. + + **Items:** + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Authorization mechanism type. + + - **`connection_id`** + + `string` — Parent connection configuration reference. + + - **`connector`** + + `string` — Connector identifier. + + - **`id`** + + `string` — Unique connected account identifier. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. + + - **`last_used_at`** + + `string`, format: `date-time` — Last usage timestamp. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft'). + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current connection status. + + - **`token_expires_at`** + + `string`, format: `date-time` — Token expiration timestamp. + + - **`updated_at`** + + `string`, format: `date-time` — Last modification timestamp. + +* **`next_page_token`** + + `string` — Pagination token for retrieving the next page. Empty if this is the last page. Pass this value to page\_token in the next request. + +* **`prev_page_token`** + + `string` — Pagination token for retrieving the previous page. Empty if this is the first page. Pass this value to page\_token to go back. + +* **`total_size`** + + `integer`, format: `int64` — Total count of connected accounts matching the filter criteria across all pages. Use for calculating pagination. + +**Example:** + +```json +{ + "connected_accounts": [ + { + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } + ], + "next_page_token": "eyJvZmZzZXQiOjIwfQ==", + "prev_page_token": "eyJvZmZzZXQiOjB9", + "total_size": 100 +} +``` + +### OAuth 2.0 access and refresh tokens with scopes + +- **Type:**`object` + +* **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + +* **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + +* **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + +* **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + +**Example:** + +```json +{ + "access_token": "ya29.a0AfH6SMBx...", + "domain": "example.com", + "refresh_token": "1//0gHJxZ-Lb2...", + "scopes": [ + "https://www.googleapis.com/auth/drive.readonly", + "https://www.googleapis.com/auth/userinfo.email" + ] +} +``` + +### Static authentication credentials for API keys, bearer tokens, or basic auth + +- **Type:**`object` + +* **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +**Example:** + +```json +{ + "details": { + "api_key": "sk_live_...", + "api_secret": "..." + } +} +``` + +### Authentication credentials container supporting multiple auth types + +- **Type:**`object` + +* **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + +* **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +**Example:** + +```json +{ + "oauth_token": { + "access_token": "ya29.a0AfH6SMBx...", + "domain": "example.com", + "refresh_token": "1//0gHJxZ-Lb2...", + "scopes": [ + "https://www.googleapis.com/auth/drive.readonly", + "https://www.googleapis.com/auth/userinfo.email" + ] + }, + "static_auth": { + "details": { + "api_key": "sk_live_...", + "api_secret": "..." + } + } +} +``` + +### Payload for updating an existing connected account - all fields optional + +- **Type:**`object` + +* **`api_config`** + + `object` — Updated JSON configuration for API-specific settings. Merges with existing configuration - only provided fields are modified. + +* **`authorization_details`** + + `object` — Updated authentication credentials. Provide new OAuth tokens (e.g., after refresh) or updated static auth details. Only included fields will be modified. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +**Example:** + +```json +{ + "api_config": { + "rate_limit": 2000, + "timeout": 60 + }, + "authorization_details": { + "oauth_token": { + "access_token": "ya29.new_token...", + "refresh_token": "1//0g...", + "scopes": [ + "email", + "profile", + "calendar" + ] + } + } +} +``` + +### connected\_accountsUpdateConnectedAccountRequest + +- **Type:**`object` + +* **`connected_account`** + + `object` — Details of the connected account to update + + - **`api_config`** + + `object` — Updated JSON configuration for API-specific settings. Merges with existing configuration - only provided fields are modified. + + - **`authorization_details`** + + `object` — Updated authentication credentials. Provide new OAuth tokens (e.g., after refresh) or updated static auth details. Only included fields will be modified. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +* **`connector`** + + `string` — Connector identifier + +* **`id`** + + `string` — Unique identifier for the connected account to update + +* **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +* **`organization_id`** + + `string` — Organization ID for the connector + +* **`user_id`** + + `string` — User ID for the connector + +**Example:** + +```json +{ + "connected_account": { + "authorization_details": { + "oauth_token": { + "access_token": "...", + "refresh_token": "...", + "scopes": [ + "read", + "write" + ] + } + }, + "authorization_type": "OAUTH2" + }, + "connector": "notion", + "id": "ca_123", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "user_id": "user_121312434123312" +} +``` + +### connected\_accountsConnectedAccount + +- **Type:**`object` + +* **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. + +* **`authorization_details`** + + `object` — Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +* **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. + +* **`connection_id`** + + `string` — Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. + +* **`connector`** + + `string` — Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to. + +* **`id`** + + `string` — Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca\_'. + +* **`identifier`** + + `string` — The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier. + +* **`last_used_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. + +* **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection. + +* **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. + +* **`token_expires_at`** + + `string`, format: `date-time` — Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. + +* **`updated_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. + +**Example:** + +```json +{ + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": { + "oauth_token": null, + "static_auth": null + }, + "authorization_type": "OAUTH", + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": "ACTIVE", + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" +} +``` + +### connected\_accountsUpdateConnectedAccountResponse + +- **Type:**`object` + +* **`connected_account`** + + `object` — The updated connected account with refreshed credentials, new token expiry, and modified configuration settings. + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. + + - **`authorization_details`** + + `object` — Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. + + - **`connection_id`** + + `string` — Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. + + - **`connector`** + + `string` — Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to. + + - **`id`** + + `string` — Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca\_'. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier. + + - **`last_used_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection. + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. + + - **`token_expires_at`** + + `string`, format: `date-time` — Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. + +**Example:** + +```json +{ + "connected_account": { + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": null, + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } +} +``` + +### Payload for creating a new connected account - authorization details are optional + +- **Type:**`object` + +* **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom API endpoints, timeouts, or feature flags. + +* **`authorization_details`** + + `object` — Optional authentication credentials for the connected account. Include OAuth tokens (access\_token, refresh\_token, scopes) or static auth details (API keys, bearer tokens). Can be provided later via update. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +**Example:** + +```json +{ + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": { + "oauth_token": { + "access_token": "ya29.a0...", + "refresh_token": "1//0g...", + "scopes": [ + "email", + "profile" + ] + } + } +} +``` + +### connected\_accountsCreateConnectedAccountRequest + +- **Type:**`object` + +* **`connected_account`** + + `object` — Details of the connected account to create + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom API endpoints, timeouts, or feature flags. + + - **`authorization_details`** + + `object` — Optional authentication credentials for the connected account. Include OAuth tokens (access\_token, refresh\_token, scopes) or static auth details (API keys, bearer tokens). Can be provided later via update. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +* **`connector`** + + `string` — Connector identifier + +* **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +* **`organization_id`** + + `string` — Organization ID for the connector + +* **`user_id`** + + `string` — User ID for the connector + +**Example:** + +```json +{ + "connected_account": { + "authorization_details": { + "oauth_token": { + "access_token": "...", + "refresh_token": "...", + "scopes": [ + "read", + "write" + ] + } + }, + "authorization_type": "OAUTH2" + }, + "connector": "notion", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "user_id": "user_121312434123312" +} +``` + +### connected\_accountsCreateConnectedAccountResponse + +- **Type:**`object` + +* **`connected_account`** + + `object` — The newly created connected account with its unique identifier, status, and complete authorization details including access tokens. + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. + + - **`authorization_details`** + + `object` — Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. + + - **`connection_id`** + + `string` — Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. + + - **`connector`** + + `string` — Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to. + + - **`id`** + + `string` — Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca\_'. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier. + + - **`last_used_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection. + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. + + - **`token_expires_at`** + + `string`, format: `date-time` — Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. + +**Example:** + +```json +{ + "connected_account": { + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": null, + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } +} +``` + +### connected\_accountsGetConnectedAccountByIdentifierResponse + +- **Type:**`object` + +* **`connected_account`** + + `object` — The connected account with complete details including sensitive authorization credentials (access tokens, refresh tokens, scopes). Handle with appropriate access controls. + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. + + - **`authorization_details`** + + `object` — Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. + + - **`connection_id`** + + `string` — Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. + + - **`connector`** + + `string` — Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to. + + - **`id`** + + `string` — Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca\_'. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier. + + - **`last_used_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection. + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. + + - **`token_expires_at`** + + `string`, format: `date-time` — Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. + +**Example:** + +```json +{ + "connected_account": { + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": null, + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } +} +``` + +### connected\_accountsGetMagicLinkForConnectedAccountRequest + +- **Type:**`object` + +* **`connector`** + + `string` — Connector identifier + +* **`id`** + + `string` — Unique identifier for the connected account + +* **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +* **`organization_id`** + + `string` — Organization ID for the connector + +* **`state`** + + `string` — Optional opaque state value. State added to the user verify redirect URL query params to validate the user verification + +* **`user_id`** + + `string` — User ID for the connector + +* **`user_verify_url`** + + `string` — B2B app's user verify redirect URL + +**Example:** + +```json +{ + "connector": "notion", + "id": "ca_123", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "state": "QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY=", + "user_id": "user_121312434123312", + "user_verify_url": "https://app.yourapp.com/user/verify/callback" +} +``` + +### connected\_accountsGetMagicLinkForConnectedAccountResponse + +- **Type:**`object` + +* **`expiry`** + + `string`, format: `date-time` — Expiry timestamp for the authentication link + +* **`link`** + + `string` — Authentication link for the connector + +**Example:** + +```json +{ + "expiry": "2024-03-20T15:04:05Z", + "link": "https://notion.com/oauth/authorize?client_id=..." +} +``` + +### connected\_accountsVerifyConnectedAccountUserRequest + +- **Type:**`object` + +* **`auth_request_id` (required)** + + `string` — Auth request ID as base64url-encoded opaque token from the user verify redirect URL query params + +* **`identifier` (required)** + + `string` — Current logged in user's connected account identifier + +**Example:** + +```json +{ + "auth_request_id": "QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY=", + "identifier": "user@example.com" +} +``` + +### connected\_accountsVerifyConnectedAccountUserResponse + +- **Type:**`object` + +* **`post_user_verify_redirect_url`** + + `string` — URL to redirect the user to after successful verification + +**Example:** + +```json +{ + "post_user_verify_redirect_url": "https://env1.example.com/connect/success" +} +``` + +### connected\_accountsDeleteConnectedAccountRequest + +- **Type:**`object` + +* **`connector`** + + `string` — Connector identifier + +* **`id`** + + `string` — Unique identifier for the connected account to delete + +* **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +* **`organization_id`** + + `string` — Organization ID for the connector + +* **`user_id`** + + `string` — User ID for the connector + +**Example:** + +```json +{ + "connector": "notion", + "id": "ca_123", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "user_id": "user_121312434123312" +} +``` + +### connected\_accountsSearchConnectedAccountsResponse + +- **Type:**`object` + +* **`connected_accounts`** + + `array` — List of connected accounts matching the search query. Excludes sensitive authorization details. + + **Items:** + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Authorization mechanism type. + + - **`connection_id`** + + `string` — Parent connection configuration reference. + + - **`connector`** + + `string` — Connector identifier. + + - **`id`** + + `string` — Unique connected account identifier. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. + + - **`last_used_at`** + + `string`, format: `date-time` — Last usage timestamp. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft'). + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current connection status. + + - **`token_expires_at`** + + `string`, format: `date-time` — Token expiration timestamp. + + - **`updated_at`** + + `string`, format: `date-time` — Last modification timestamp. + +* **`next_page_token`** + + `string` — Pagination token for the next page. Empty if this is the last page. + +* **`prev_page_token`** + + `string` — Pagination token for the previous page. Empty if this is the first page. + +* **`total_size`** + + `integer`, format: `int64` — Total count of accounts matching the search query across all pages. + +**Example:** + +```json +{ + "connected_accounts": [ + { + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } + ], + "next_page_token": "eyJvZmZzZXQiOjMwfQ==", + "prev_page_token": "eyJvZmZzZXQiOjB9", + "total_size": 100 +} +``` + +### toolsExecuteToolRequest + +- **Type:**`object` + +* **`connected_account_id`** + + `string` — Optional. The unique ID of the connected account. Use this to directly identify the connected account instead of using identifier + connector combination. + +* **`connector`** + + `string` — Optional. The name of the connector/provider (e.g., 'Google Workspace', 'Slack', 'Notion'). Use this in combination with identifier to identify the connected account. + +* **`identifier`** + + `string` — Optional. The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). Use this in combination with connector to identify the connected account. + +* **`organization_id`** + + `string` — Optional. The organization ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple organizations. + +* **`params`** + + `object` — JSON object containing the parameters required for tool execution. The structure depends on the specific tool being executed. + +* **`tool_name`** + + `string` — Name of the tool to execute + +* **`user_id`** + + `string` — Optional. The user ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple users. + +**Example:** + +```json +{ + "connected_account_id": "ca_123", + "connector": "Google Workspace", + "identifier": "user@example.com", + "organization_id": "org_123", + "params": { + "body": "Hello World", + "subject": "Hello", + "to": "user@example.com" + }, + "tool_name": "send_email", + "user_id": "user_123" +} +``` + +### toolsExecuteToolResponse + +- **Type:**`object` + +* **`data`** + + `object` — Free-flowing JSON parameters for the tool execution + +* **`execution_id`** + + `string` — Unique identifier for the tool execution + +**Example:** + +```json +{ + "data": { + "body": "Hello World", + "subject": "Hello", + "to": "user@example.com" + }, + "execution_id": "123456789" +} +``` + +### ScalekitEvent + +- **Type:**`object` + +* **`environment_id` (required)** + + `string` — The environment ID where the event occurred + +* **`id` (required)** + + `string` — Unique identifier for the webhook event (must be prefixed with "evt\_") + +* **`object` (required)** + + `string`, possible values: `"Organization", "Connection", "Role", "Directory", "DirectoryUser", "DirectoryGroup", "Permission", "OrgMembership", "User"` — The type of object that triggered the webhook + +* **`occurred_at` (required)** + + `string`, format: `date-time` — When the event occurred (ISO 8601 format) + +* **`spec_version` (required)** + + `string` — The webhook specification version + +* **`type` (required)** + + `string`, possible values: `"organization.created", "organization.updated", "organization.deleted", "organization.sso_created", "organization.sso_deleted", "organization.sso_enabled", "organization.sso_disabled", "user.signup", "user.login", "user.logout", "user.organization_invitation", "user.organization_membership_created", "user.organization_membership_updated", "user.organization_membership_deleted", "organization.directory.user_created", "organization.directory.user_updated", "organization.directory.user_deleted", "organization.directory.group_created", "organization.directory.group_updated", "organization.directory.group_deleted", "organization.directory_enabled", "organization.directory_disabled", "role.created", "role.updated", "role.deleted", "permission.created", "permission.updated", "permission.deleted"` — The event type + +* **`data`** + + `object` — The event payload (structure varies by event type) + +* **`display_name`** + + `string` — Human-readable display name for the event + +* **`organization_id`** + + `string` — The organization ID (if applicable) + +**Example:** + +```json +{ + "spec_version": "1", + "id": "evt_1234567890abcdef", + "type": "organization.created", + "occurred_at": "2024-01-01T00:00:00Z", + "environment_id": "env_1234567890abcdef", + "organization_id": "org_1234567890abcdef", + "object": "Organization", + "data": { + "id": "org_1234567890abcdef", + "name": "Example Organization", + "created_at": "2024-01-01T00:00:00Z" + }, + "display_name": "Organization Created" +} +``` diff --git a/public/api/agentkit.scalar.json b/public/api/agentkit.scalar.json new file mode 100644 index 000000000..b94e3407e --- /dev/null +++ b/public/api/agentkit.scalar.json @@ -0,0 +1,1834 @@ +{ + "openapi": "3.1.1", + "info": { + "description": "The AgentKit API enables you to manage connected accounts for third-party integrations, execute tools on behalf of users, and handle OAuth connections to external services like Google, Notion, Slack, and other applications.\n\n## Quickstart\n\nThe Scalekit API uses OAuth 2.0 Client Credentials for authentication.\n\nCopy your API credentials from the Scalekit dashboard's API Config section and set them as environment variables.\n\n```sh\nSCALEKIT_ENVIRONMENT_URL=''\nSCALEKIT_CLIENT_ID=''\nSCALEKIT_CLIENT_SECRET=''\n```\n\nGetting an access token\n\n1. Get your credentials from the [Scalekit Dashboard](https://app.scalekit.com)\n2. Request an access token:\n\n```sh\ncurl https:///oauth/token \\\n -X POST \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d 'client_id={client_id}' \\\n -d 'client_secret={client_secret}' \\\n -d 'grant_type=client_credentials'\n```\n\n3. Use the access token in API requests:\n\n```sh\ncurl https:///api/v1/connected_accounts \\\n -H 'Content-Type: application/json' \\\n -H 'Authorization: Bearer {access_token}'\n```\n", + "title": "AgentKit APIs", + "contact": { + "name": "Scalekit Inc", + "url": "https://scalekit.com", + "email": "support@scalekit.com" + }, + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0" + }, + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://$SCALEKIT_ENVIRONMENT_URL" + } + ], + "security": [ + { + "oauth2": [] + } + ], + "tags": [ + { + "description": "Manage connected accounts for third-party integrations and OAuth connections. Connected accounts represent authenticated access to external services like Google, Notion, Slack, and other applications.", + "name": "Connected Accounts" + } + ], + "externalDocs": { + "description": "Scalekit Docs", + "url": "https://docs.scalekit.com/" + }, + "paths": { + "/api/v1/connected_accounts": { + "get": { + "description": "Retrieves a paginated list of connected accounts for third-party integrations. Filter by organization, user, connector type, provider, or identifier. Returns OAuth tokens, API keys, and connection status for each account. Use pagination tokens to navigate through large result sets.", + "tags": [ + "Connected Accounts" + ], + "summary": "List connected accounts", + "operationId": "ConnectedAccountService_ListConnectedAccounts", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Filter by organization ID. Returns only connected accounts associated with this organization.", + "name": "organization_id", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Filter by user ID. Returns only connected accounts associated with this user.", + "name": "user_id", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Filter by connector type. Connector identifier such as 'notion', 'slack', 'google', etc. Alphanumeric with spaces, hyphens, underscores, and colons allowed.", + "name": "connector", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Filter by account identifier. The unique identifier for the connected account within the third-party service (e.g., email address, workspace ID).", + "name": "identifier", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Filter by OAuth provider. The authentication provider name such as 'google', 'microsoft', 'github', etc.", + "name": "provider", + "in": "query" + }, + { + "schema": { + "type": "integer", + "format": "int64" + }, + "description": "Maximum number of connected accounts to return per page. Must be between 0 and 100. Default is typically 10.", + "name": "page_size", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Pagination token from a previous response. Use the next_page_token value from ListConnectedAccountsResponse to fetch the next page.", + "name": "page_token", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Text search query to filter connected accounts by name, identifier, or other searchable fields. Case-insensitive.", + "name": "query", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved the list of connected accounts with their authentication details and status", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connected_accountsListConnectedAccountsResponse" + } + } + } + }, + "400": { + "description": "Invalid request - occurs when query parameters are malformed or validation fails", + "content": { + "application/json": { + "schema": {} + } + } + }, + "401": { + "description": "Authentication required - missing or invalid access token", + "content": { + "application/json": { + "schema": {} + } + } + } + } + }, + "put": { + "description": "Updates authentication credentials and configuration for an existing connected account. Modify OAuth tokens, refresh tokens, access scopes, or API configuration settings. Specify the account by ID, or by combination of organization/user, connector, and identifier. Returns the updated account with new token expiry and status information.", + "tags": [ + "Connected Accounts" + ], + "summary": "Update connected account credentials", + "operationId": "ConnectedAccountService_UpdateConnectedAccount", + "responses": { + "200": { + "description": "Connected account updated successfully with new credentials or configuration", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connected_accountsUpdateConnectedAccountResponse" + } + } + } + }, + "400": { + "description": "Invalid request - missing required fields, invalid authorization details, or validation failed", + "content": { + "application/json": { + "schema": {} + } + } + }, + "401": { + "description": "Authentication required - missing or invalid access token", + "content": { + "application/json": { + "schema": {} + } + } + }, + "404": { + "description": "Connected account not found - the specified account does not exist", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connected_accountsUpdateConnectedAccountRequest" + } + } + }, + "required": true + } + }, + "post": { + "description": "Creates a new connected account with OAuth tokens or API credentials for third-party service integration. Supply authorization details including access tokens, refresh tokens, scopes, and optional API configuration. The account can be scoped to an organization or user. Returns the created account with its unique identifier and authentication status.", + "tags": [ + "Connected Accounts" + ], + "summary": "Create a connected account", + "operationId": "ConnectedAccountService_CreateConnectedAccount", + "responses": { + "201": { + "description": "Connected account created successfully with authentication credentials stored securely", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connected_accountsCreateConnectedAccountResponse" + } + } + } + }, + "400": { + "description": "Invalid request - missing required fields, invalid authorization details, or validation failed", + "content": { + "application/json": { + "schema": {} + } + } + }, + "401": { + "description": "Authentication required - missing or invalid access token", + "content": { + "application/json": { + "schema": {} + } + } + }, + "409": { + "description": "Conflict - connected account with the same identifier already exists", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connected_accountsCreateConnectedAccountRequest" + } + } + }, + "required": true + } + } + }, + "/api/v1/connected_accounts/auth": { + "get": { + "description": "Retrieves complete authentication details for a connected account including OAuth tokens, refresh tokens, scopes, and API configuration. Query by account ID or by combination of organization/user, connector, and identifier. Returns sensitive credential information - use appropriate access controls.", + "tags": [ + "Connected Accounts" + ], + "summary": "Get connected account details", + "operationId": "ConnectedAccountService_GetConnectedAccountAuth", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Organization ID for the connector", + "name": "organization_id", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "User ID for the connector", + "name": "user_id", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Connector identifier", + "name": "connector", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier).", + "name": "identifier", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Unique identifier for the connected account", + "name": "id", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved connected account with full authentication details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connected_accountsGetConnectedAccountByIdentifierResponse" + } + } + } + }, + "400": { + "description": "Invalid request - missing required query parameters", + "content": { + "application/json": { + "schema": {} + } + } + }, + "401": { + "description": "Authentication required - missing or invalid access token", + "content": { + "application/json": { + "schema": {} + } + } + }, + "404": { + "description": "Connected account not found - no account matches the specified criteria", + "content": { + "application/json": { + "schema": {} + } + } + } + } + } + }, + "/api/v1/connected_accounts/magic_link": { + "post": { + "description": "Creates a time-limited magic link for connecting or re-authorizing a third-party account. The link directs users to the OAuth authorization flow for the specified connector. Returns the generated link URL and expiration timestamp. Links typically expire after a short duration for security.", + "tags": [ + "Connected Accounts" + ], + "summary": "Generate authentication magic link", + "operationId": "ConnectedAccountService_GetMagicLinkForConnectedAccount", + "responses": { + "200": { + "description": "Magic link generated successfully with authorization URL and expiry time", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connected_accountsGetMagicLinkForConnectedAccountResponse" + } + } + } + }, + "400": { + "description": "Invalid request - missing required parameters or invalid connector", + "content": { + "application/json": { + "schema": {} + } + } + }, + "401": { + "description": "Authentication required - missing or invalid access token", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connected_accountsGetMagicLinkForConnectedAccountRequest" + } + } + }, + "required": true + } + } + }, + "/api/v1/connected_accounts/user/verify": { + "post": { + "description": "Confirms the user assertion and activates the connected account after the user completes third-party OAuth. Called by the B2B app server with auth_request_id and identifier. Validates that the asserted identifier matches the one stored on the auth request and promotes pending tokens to live.", + "tags": [ + "Connected Accounts" + ], + "summary": "Verify connected account user", + "operationId": "ConnectedAccountService_VerifyConnectedAccountUser", + "responses": { + "200": { + "description": "Verification successful; connected account is now ACTIVE", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connected_accountsVerifyConnectedAccountUserResponse" + } + } + } + }, + "400": { + "description": "Invalid request - missing or malformed fields", + "content": { + "application/json": { + "schema": {} + } + } + }, + "401": { + "description": "Unauthorized - invalid or missing access token", + "content": { + "application/json": { + "schema": {} + } + } + }, + "403": { + "description": "Forbidden - identifier mismatch", + "content": { + "application/json": { + "schema": {} + } + } + }, + "404": { + "description": "Not found - no pending flow for the given auth_request_id or already consumed", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connected_accountsVerifyConnectedAccountUserRequest" + } + } + }, + "required": true + } + } + }, + "/api/v1/connected_accounts:delete": { + "post": { + "description": "Permanently removes a connected account and revokes all associated authentication credentials. Identify the account by ID, or by combination of organization/user, connector, and identifier. This action cannot be undone. All OAuth tokens and API keys for this account will be invalidated.", + "tags": [ + "Connected Accounts" + ], + "summary": "Delete a connected account", + "operationId": "ConnectedAccountService_DeleteConnectedAccount", + "responses": { + "200": { + "description": "Connected account deleted successfully and all credentials revoked", + "content": { + "application/json": { + "schema": {} + } + } + }, + "400": { + "description": "Invalid request - malformed parameters or validation failed", + "content": { + "application/json": { + "schema": {} + } + } + }, + "401": { + "description": "Authentication required - missing or invalid access token", + "content": { + "application/json": { + "schema": {} + } + } + }, + "404": { + "description": "Connected account not found - the specified account does not exist", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connected_accountsDeleteConnectedAccountRequest" + } + } + }, + "required": true + } + } + }, + "/api/v1/connected_accounts:search": { + "get": { + "description": "Search for connected accounts in your environment using a text query that matches against identifiers, providers, or connectors. The search performs case-insensitive matching across account details. Returns paginated results with account status and authentication type information.", + "tags": [ + "Connected Accounts" + ], + "summary": "Search connected accounts", + "operationId": "ConnectedAccountService_SearchConnectedAccounts", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Search term to match against connected account identifiers, providers, or connectors. Must be at least 3 characters. Case insensitive.", + "name": "query", + "in": "query" + }, + { + "schema": { + "type": "integer", + "format": "int64" + }, + "description": "Maximum number of connected accounts to return per page. Value must be between 1 and 30.", + "name": "page_size", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Token from a previous response for pagination. Provide this to retrieve the next page of results.", + "name": "page_token", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Connection ID to filter connected accounts", + "name": "connection_id", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved matching connected accounts with pagination support", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connected_accountsSearchConnectedAccountsResponse" + } + } + } + }, + "400": { + "description": "Invalid request - query parameter is too short (minimum 3 characters) or validation failed", + "content": { + "application/json": { + "schema": {} + } + } + }, + "401": { + "description": "Authentication required - missing or invalid access token", + "content": { + "application/json": { + "schema": {} + } + } + } + } + } + }, + "/api/v1/execute_tool": { + "post": { + "description": "Executes a tool action using authentication credentials from a connected account. Specify the tool by name and provide required parameters as JSON. The connected account can be identified by ID, or by combination of organization/user, connector, and identifier. Returns the execution result data and a unique execution ID for tracking. Use this endpoint to perform actions like sending emails, creating calendar events, or managing resources in external services.", + "tags": [ + "Connected Accounts" + ], + "summary": "Execute a tool using a connected account", + "operationId": "ToolService_ExecuteTool", + "responses": { + "200": { + "description": "Tool executed successfully with result data and execution ID", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/toolsExecuteToolResponse" + } + } + } + }, + "400": { + "description": "Invalid request - occurs when tool name is missing, parameters are malformed, or tool definition validation fails", + "content": { + "application/json": { + "schema": {} + } + } + }, + "401": { + "description": "Authentication required - missing or invalid access token", + "content": { + "application/json": { + "schema": {} + } + } + }, + "404": { + "description": "Tool or connected account not found - occurs when the specified tool name or connected account does not exist", + "content": { + "application/json": { + "schema": {} + } + } + }, + "500": { + "description": "Tool execution failed - occurs when the external service returns an error or the tool encounters a runtime exception", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/toolsExecuteToolRequest" + } + } + }, + "required": true + } + } + } + }, + "webhooks": { + "connected_account.created": { + "post": { + "summary": "Connected Account Created", + "description": "Triggered when a new connected account is created", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_101531404017336586", + "type": "connected_account.created", + "object": "ConnectedAccount", + "occurred_at": "2025-12-01T10:23:52.702980847Z", + "environment_id": "env_88640229614813449", + "data": { + "authorization_type": "OAUTH", + "connection_id": "conn_100668583155073286", + "id": "ca_101531404000559370", + "identifier": "Bruce", + "provider": "CANVA", + "status": "PENDING_AUTH" + } + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "connected_account.updated": { + "post": { + "summary": "Connected Account Updated", + "description": "Triggered when a connected account is updated", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_101652975398683158", + "type": "connected_account.updated", + "object": "ConnectedAccount", + "occurred_at": "2025-12-02T06:31:34.895815554Z", + "environment_id": "env_88640229614813449", + "display_name": "Connected account updated", + "data": { + "authorization_type": "OAUTH", + "connection_id": "conn_100510054016352776", + "id": "ca_100510623602835982", + "identifier": "Pranesh", + "provider": "SUPABASE", + "status": "PENDING_AUTH" + } + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "connected_account.deleted": { + "post": { + "summary": "Connected Account Deleted", + "description": "Triggered when a connected account is deleted", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_101653010731500290", + "type": "connected_account.deleted", + "object": "ConnectedAccount", + "occurred_at": "2025-12-02T06:31:55.954027187Z", + "environment_id": "env_88640229614813449", + "display_name": "connected account deleted", + "data": { + "authorization_type": "OAUTH", + "connection_id": "conn_101644109747323155", + "id": "ca_101649788113519113", + "identifier": "Clark", + "last_used_at": "2025-12-02T06:00:01.374253Z", + "provider": "GOOGLE_ADS", + "status": "ACTIVE", + "token_expires_at": "2025-12-02T06:59:57.237447Z" + } + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "connected_account.magic_link_generated": { + "post": { + "summary": "Connected Account Magic Link Generated", + "description": "Triggered when a magic link is generated for OAuth flow", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_101652975398683158", + "type": "connected_account.magic_link_generated", + "object": "ConnectedAccount", + "occurred_at": "2025-12-02T06:31:34.895815554Z", + "environment_id": "env_88640229614813448", + "data": { + "authorization_type": "OAUTH", + "connection_id": "conn_100510054016352776", + "id": "ca_100510623602835982", + "identifier": "Pranesh", + "provider": "SUPABASE", + "status": "PENDING_AUTH" + } + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "connected_account.oauth_tokens_fetched": { + "post": { + "summary": "Connected Account OAuth Tokens Fetched", + "description": "Triggered when OAuth tokens are successfully fetched", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_101649795042509316", + "type": "connected_account.oauth_tokens_fetched", + "object": "ConnectedAccount", + "occurred_at": "2025-12-02T05:59:59.250126407Z", + "environment_id": "env_88640229614813449", + "data": { + "authorization_type": "OAUTH", + "connection_id": "conn_101644109747323155", + "id": "ca_101649788113519113", + "identifier": "Clark", + "provider": "GOOGLE_ADS", + "status": "ACTIVE", + "token_expires_at": "2025-12-02T06:59:57.237447778Z" + } + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "connected_account.token_refresh_succeeded": { + "post": { + "summary": "Connected Account Token Refresh Succeeded", + "description": "Triggered when token refresh succeeds", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_101651946317808143", + "type": "connected_account.token_refresh_succeeded", + "object": "ConnectedAccount", + "occurred_at": "2025-12-02T06:21:21.517480021Z", + "environment_id": "env_88640229614813449", + "data": { + "authorization_type": "OAUTH", + "connection_id": "conn_101644109747323155", + "id": "ca_101644170698948883", + "identifier": "Pranesh", + "last_used_at": "2025-12-02T06:21:21.393723232Z", + "provider": "GOOGLE_ADS", + "status": "ACTIVE", + "token_expires_at": "2025-12-02T07:21:20.508197312Z" + } + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "connected_account.token_refresh_failed": { + "post": { + "summary": "Connected Account Token Refresh Failed", + "description": "Triggered when token refresh fails", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_101649795042509316", + "type": "connected_account.token_refresh_failed", + "object": "ConnectedAccount", + "occurred_at": "2025-12-02T05:59:59.250126407Z", + "environment_id": "env_88640229614813445", + "data": { + "authorization_type": "OAUTH", + "connection_id": "conn_101644109747323155", + "id": "ca_101649788113519113", + "identifier": "Clark", + "provider": "GOOGLE_ADS", + "status": "ACTIVE", + "token_expires_at": "2025-12-02T06:59:57.237447778Z" + } + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "connected_account.oauth_succeeded": { + "post": { + "summary": "Connected Account OAuth Succeeded", + "description": "Triggered when OAuth authentication succeeds", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_101649484227871236", + "type": "connected_account.oauth_succeeded", + "object": "ConnectedAccount", + "occurred_at": "2025-12-02T05:56:53.994604757Z", + "environment_id": "env_88640229614813449", + "data": { + "authorization_type": "OAUTH", + "connection_id": "conn_101644109747323155", + "id": "ca_101649474950005257", + "identifier": "Bruce", + "provider": "GOOGLE_ADS", + "status": "ACTIVE", + "token_expires_at": "2025-12-02T06:56:52.976081699Z" + } + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + } + }, + "components": { + "securitySchemes": { + "oauth2": { + "type": "oauth2", + "flows": { + "clientCredentials": { + "tokenUrl": "https://$SCALEKIT_ENVIRONMENT_URL/oauth/token", + "scopes": { + "": "No scope required for client credentials flow" + } + } + } + } + }, + "schemas": { + "connected_accountsConnectorType": { + "description": "- OAUTH: OAuth 2.0 authorization with access and refresh tokens\n - API_KEY: Static API key authentication\n - BASIC_AUTH: HTTP Basic Authentication (username/password)\n - BEARER_TOKEN: Bearer token authentication\n - CUSTOM: Custom authentication mechanism\n - BASIC: Basic authentication (alias)", + "type": "string", + "title": "Type of authentication mechanism used for the connected account", + "enum": [ + "OAUTH", + "API_KEY", + "BASIC_AUTH", + "BEARER_TOKEN", + "CUSTOM", + "BASIC" + ] + }, + "connected_accountsConnectorStatus": { + "description": "- ACTIVE: Account is connected and credentials are valid\n - EXPIRED: Access token has expired and needs refresh\n - PENDING_AUTH: Account awaiting user authorization (re-auth initiated)\n - PENDING_VERIFICATION: OAuth complete; awaiting user identity verification\nbefore activation", + "type": "string", + "title": "Status of a connected account indicating its current state", + "enum": [ + "ACTIVE", + "EXPIRED", + "PENDING_AUTH", + "PENDING_VERIFICATION" + ] + }, + "connected_accountsConnectedAccountForList": { + "type": "object", + "title": "Connected account summary for list operations - excludes sensitive authorization details", + "properties": { + "authorization_type": { + "description": "Authorization mechanism type.", + "$ref": "#/components/schemas/connected_accountsConnectorType" + }, + "connection_id": { + "description": "Parent connection configuration reference.", + "type": "string", + "examples": [ + "conn_24834495392086178" + ] + }, + "connector": { + "description": "Connector identifier.", + "type": "string", + "examples": [ + "notion" + ] + }, + "id": { + "description": "Unique connected account identifier.", + "type": "string", + "examples": [ + "ca_24834495392086178" + ] + }, + "identifier": { + "description": "The unique identifier for this account in the third-party service.", + "type": "string", + "examples": [ + "user@example.com" + ] + }, + "last_used_at": { + "description": "Last usage timestamp.", + "type": "string", + "format": "date-time", + "examples": [ + "2024-03-20T14:30:00Z" + ] + }, + "provider": { + "description": "OAuth provider name (e.g., 'google', 'microsoft').", + "type": "string", + "examples": [ + "google" + ] + }, + "status": { + "description": "Current connection status.", + "$ref": "#/components/schemas/connected_accountsConnectorStatus" + }, + "token_expires_at": { + "description": "Token expiration timestamp.", + "type": "string", + "format": "date-time", + "examples": [ + "2024-12-31T23:59:59Z" + ] + }, + "updated_at": { + "description": "Last modification timestamp.", + "type": "string", + "format": "date-time", + "examples": [ + "2024-03-20T15:04:05Z" + ] + } + } + }, + "connected_accountsListConnectedAccountsResponse": { + "type": "object", + "properties": { + "connected_accounts": { + "description": "List of connected accounts matching the filter criteria. Excludes sensitive authorization details for security.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/connected_accountsConnectedAccountForList" + } + }, + "next_page_token": { + "description": "Pagination token for retrieving the next page. Empty if this is the last page. Pass this value to page_token in the next request.", + "type": "string", + "examples": [ + "eyJvZmZzZXQiOjIwfQ==" + ] + }, + "prev_page_token": { + "description": "Pagination token for retrieving the previous page. Empty if this is the first page. Pass this value to page_token to go back.", + "type": "string", + "examples": [ + "eyJvZmZzZXQiOjB9" + ] + }, + "total_size": { + "description": "Total count of connected accounts matching the filter criteria across all pages. Use for calculating pagination.", + "type": "integer", + "format": "int64", + "examples": [ + 100 + ] + } + } + }, + "connected_accountsOauthToken": { + "type": "object", + "title": "OAuth 2.0 access and refresh tokens with scopes", + "properties": { + "access_token": { + "description": "OAuth access token for API requests. Typically short-lived and must be refreshed after expiration.", + "type": "string", + "examples": [ + "ya29.a0AfH6SMBx..." + ] + }, + "domain": { + "description": "Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain).", + "type": "string", + "examples": [ + "example.com" + ] + }, + "refresh_token": { + "description": "OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization.", + "type": "string", + "examples": [ + "1//0gHJxZ-Lb2..." + ] + }, + "scopes": { + "description": "List of granted OAuth scopes defining the permissions and access levels for this connection.", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "https://www.googleapis.com/auth/drive.readonly", + "https://www.googleapis.com/auth/userinfo.email" + ] + ] + } + } + }, + "connected_accountsStaticAuth": { + "type": "object", + "title": "Static authentication credentials for API keys, bearer tokens, or basic auth", + "properties": { + "details": { + "description": "Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.).", + "type": "object", + "examples": [ + { + "api_key": "sk_live_...", + "api_secret": "..." + } + ] + } + } + }, + "connected_accountsAuthorizationDetails": { + "type": "object", + "title": "Authentication credentials container supporting multiple auth types", + "properties": { + "oauth_token": { + "title": "OAuth 2.0 credentials", + "$ref": "#/components/schemas/connected_accountsOauthToken" + }, + "static_auth": { + "title": "Static authentication credentials", + "$ref": "#/components/schemas/connected_accountsStaticAuth" + } + } + }, + "v1connected_accountsUpdateConnectedAccount": { + "type": "object", + "title": "Payload for updating an existing connected account - all fields optional", + "properties": { + "api_config": { + "description": "Updated JSON configuration for API-specific settings. Merges with existing configuration - only provided fields are modified.", + "type": "object", + "examples": [ + { + "rate_limit": 2000, + "timeout": 60 + } + ] + }, + "authorization_details": { + "description": "Updated authentication credentials. Provide new OAuth tokens (e.g., after refresh) or updated static auth details. Only included fields will be modified.", + "$ref": "#/components/schemas/connected_accountsAuthorizationDetails", + "examples": [ + { + "oauth_token": { + "access_token": "ya29.new_token...", + "refresh_token": "1//0g...", + "scopes": [ + "email", + "profile", + "calendar" + ] + } + } + ] + } + } + }, + "connected_accountsUpdateConnectedAccountRequest": { + "type": "object", + "properties": { + "connected_account": { + "description": "Details of the connected account to update", + "$ref": "#/components/schemas/v1connected_accountsUpdateConnectedAccount", + "examples": [ + { + "authorization_details": { + "oauth_token": { + "access_token": "...", + "refresh_token": "...", + "scopes": [ + "read", + "write" + ] + } + }, + "authorization_type": "OAUTH2" + } + ] + }, + "connector": { + "description": "Connector identifier", + "type": "string", + "examples": [ + "notion" + ] + }, + "id": { + "description": "Unique identifier for the connected account to update", + "type": "string", + "examples": [ + "ca_123" + ] + }, + "identifier": { + "description": "The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier).", + "type": "string", + "examples": [ + "user@example.com" + ] + }, + "organization_id": { + "description": "Organization ID for the connector", + "type": "string", + "examples": [ + "org_121312434123312" + ] + }, + "user_id": { + "description": "User ID for the connector", + "type": "string", + "examples": [ + "user_121312434123312" + ] + } + } + }, + "connected_accountsConnectedAccount": { + "type": "object", + "properties": { + "api_config": { + "description": "Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags.", + "type": "object", + "examples": [ + { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + } + ] + }, + "authorization_details": { + "description": "Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details.", + "$ref": "#/components/schemas/connected_accountsAuthorizationDetails" + }, + "authorization_type": { + "description": "Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods.", + "$ref": "#/components/schemas/connected_accountsConnectorType" + }, + "connection_id": { + "description": "Reference to the parent connection configuration. Links this account to a specific connector setup in your environment.", + "type": "string", + "examples": [ + "conn_24834495392086178" + ] + }, + "connector": { + "description": "Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to.", + "type": "string", + "examples": [ + "notion" + ] + }, + "id": { + "description": "Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca_'.", + "type": "string", + "examples": [ + "ca_24834495392086178" + ] + }, + "identifier": { + "description": "The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier.", + "type": "string", + "examples": [ + "user@example.com" + ] + }, + "last_used_at": { + "description": "Timestamp when this connected account was last used to make an API call. Useful for tracking active connections.", + "type": "string", + "format": "date-time", + "examples": [ + "2024-03-20T14:30:00Z" + ] + }, + "provider": { + "description": "OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection.", + "type": "string", + "examples": [ + "google" + ] + }, + "status": { + "description": "Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification.", + "$ref": "#/components/schemas/connected_accountsConnectorStatus" + }, + "token_expires_at": { + "description": "Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized.", + "type": "string", + "format": "date-time", + "examples": [ + "2024-12-31T23:59:59Z" + ] + }, + "updated_at": { + "description": "Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes.", + "type": "string", + "format": "date-time", + "examples": [ + "2024-03-20T15:04:05Z" + ] + } + } + }, + "connected_accountsUpdateConnectedAccountResponse": { + "type": "object", + "properties": { + "connected_account": { + "description": "The updated connected account with refreshed credentials, new token expiry, and modified configuration settings.", + "$ref": "#/components/schemas/connected_accountsConnectedAccount" + } + } + }, + "v1connected_accountsCreateConnectedAccount": { + "type": "object", + "title": "Payload for creating a new connected account - authorization details are optional", + "properties": { + "api_config": { + "description": "Optional JSON configuration for connector-specific API settings such as rate limits, custom API endpoints, timeouts, or feature flags.", + "type": "object", + "examples": [ + { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + } + ] + }, + "authorization_details": { + "description": "Optional authentication credentials for the connected account. Include OAuth tokens (access_token, refresh_token, scopes) or static auth details (API keys, bearer tokens). Can be provided later via update.", + "$ref": "#/components/schemas/connected_accountsAuthorizationDetails", + "examples": [ + { + "oauth_token": { + "access_token": "ya29.a0...", + "refresh_token": "1//0g...", + "scopes": [ + "email", + "profile" + ] + } + } + ] + } + } + }, + "connected_accountsCreateConnectedAccountRequest": { + "type": "object", + "properties": { + "connected_account": { + "description": "Details of the connected account to create", + "$ref": "#/components/schemas/v1connected_accountsCreateConnectedAccount", + "examples": [ + { + "authorization_details": { + "oauth_token": { + "access_token": "...", + "refresh_token": "...", + "scopes": [ + "read", + "write" + ] + } + }, + "authorization_type": "OAUTH2" + } + ] + }, + "connector": { + "description": "Connector identifier", + "type": "string", + "examples": [ + "notion" + ] + }, + "identifier": { + "description": "The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier).", + "type": "string", + "examples": [ + "user@example.com" + ] + }, + "organization_id": { + "description": "Organization ID for the connector", + "type": "string", + "examples": [ + "org_121312434123312" + ] + }, + "user_id": { + "description": "User ID for the connector", + "type": "string", + "examples": [ + "user_121312434123312" + ] + } + } + }, + "connected_accountsCreateConnectedAccountResponse": { + "type": "object", + "properties": { + "connected_account": { + "description": "The newly created connected account with its unique identifier, status, and complete authorization details including access tokens.", + "$ref": "#/components/schemas/connected_accountsConnectedAccount" + } + } + }, + "connected_accountsGetConnectedAccountByIdentifierResponse": { + "type": "object", + "properties": { + "connected_account": { + "description": "The connected account with complete details including sensitive authorization credentials (access tokens, refresh tokens, scopes). Handle with appropriate access controls.", + "$ref": "#/components/schemas/connected_accountsConnectedAccount" + } + } + }, + "connected_accountsGetMagicLinkForConnectedAccountRequest": { + "type": "object", + "properties": { + "connector": { + "description": "Connector identifier", + "type": "string", + "examples": [ + "notion" + ] + }, + "id": { + "description": "Unique identifier for the connected account", + "type": "string", + "examples": [ + "ca_123" + ] + }, + "identifier": { + "description": "The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier).", + "type": "string", + "examples": [ + "user@example.com" + ] + }, + "organization_id": { + "description": "Organization ID for the connector", + "type": "string", + "examples": [ + "org_121312434123312" + ] + }, + "state": { + "description": "Optional opaque state value. State added to the user verify redirect URL query params to validate the user verification", + "type": "string", + "examples": [ + "QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY=" + ] + }, + "user_id": { + "description": "User ID for the connector", + "type": "string", + "examples": [ + "user_121312434123312" + ] + }, + "user_verify_url": { + "description": "B2B app's user verify redirect URL", + "type": "string", + "examples": [ + "https://app.yourapp.com/user/verify/callback" + ] + } + } + }, + "connected_accountsGetMagicLinkForConnectedAccountResponse": { + "type": "object", + "properties": { + "expiry": { + "description": "Expiry timestamp for the authentication link", + "type": "string", + "format": "date-time", + "examples": [ + "2024-03-20T15:04:05Z" + ] + }, + "link": { + "description": "Authentication link for the connector", + "type": "string", + "examples": [ + "https://notion.com/oauth/authorize?client_id=..." + ] + } + } + }, + "connected_accountsVerifyConnectedAccountUserRequest": { + "type": "object", + "required": [ + "auth_request_id", + "identifier" + ], + "properties": { + "auth_request_id": { + "description": "Auth request ID as base64url-encoded opaque token from the user verify redirect URL query params", + "type": "string", + "examples": [ + "QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY=" + ] + }, + "identifier": { + "description": "Current logged in user's connected account identifier", + "type": "string", + "examples": [ + "user@example.com" + ] + } + } + }, + "connected_accountsVerifyConnectedAccountUserResponse": { + "type": "object", + "properties": { + "post_user_verify_redirect_url": { + "description": "URL to redirect the user to after successful verification", + "type": "string", + "examples": [ + "https://env1.example.com/connect/success" + ] + } + } + }, + "connected_accountsDeleteConnectedAccountRequest": { + "type": "object", + "properties": { + "connector": { + "description": "Connector identifier", + "type": "string", + "examples": [ + "notion" + ] + }, + "id": { + "description": "Unique identifier for the connected account to delete", + "type": "string", + "examples": [ + "ca_123" + ] + }, + "identifier": { + "description": "The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier).", + "type": "string", + "examples": [ + "user@example.com" + ] + }, + "organization_id": { + "description": "Organization ID for the connector", + "type": "string", + "examples": [ + "org_121312434123312" + ] + }, + "user_id": { + "description": "User ID for the connector", + "type": "string", + "examples": [ + "user_121312434123312" + ] + } + } + }, + "connected_accountsSearchConnectedAccountsResponse": { + "type": "object", + "properties": { + "connected_accounts": { + "description": "List of connected accounts matching the search query. Excludes sensitive authorization details.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/connected_accountsConnectedAccountForList" + } + }, + "next_page_token": { + "description": "Pagination token for the next page. Empty if this is the last page.", + "type": "string", + "examples": [ + "eyJvZmZzZXQiOjMwfQ==" + ] + }, + "prev_page_token": { + "description": "Pagination token for the previous page. Empty if this is the first page.", + "type": "string", + "examples": [ + "eyJvZmZzZXQiOjB9" + ] + }, + "total_size": { + "description": "Total count of accounts matching the search query across all pages.", + "type": "integer", + "format": "int64", + "examples": [ + 100 + ] + } + } + }, + "toolsExecuteToolRequest": { + "type": "object", + "properties": { + "connected_account_id": { + "description": "Optional. The unique ID of the connected account. Use this to directly identify the connected account instead of using identifier + connector combination.", + "type": "string", + "examples": [ + "ca_123" + ] + }, + "connector": { + "description": "Optional. The name of the connector/provider (e.g., 'Google Workspace', 'Slack', 'Notion'). Use this in combination with identifier to identify the connected account.", + "type": "string", + "examples": [ + "Google Workspace" + ] + }, + "identifier": { + "description": "Optional. The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). Use this in combination with connector to identify the connected account.", + "type": "string", + "examples": [ + "user@example.com" + ] + }, + "organization_id": { + "description": "Optional. The organization ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple organizations.", + "type": "string", + "examples": [ + "org_123" + ] + }, + "params": { + "description": "JSON object containing the parameters required for tool execution. The structure depends on the specific tool being executed.", + "type": "object", + "examples": [ + { + "body": "Hello World", + "subject": "Hello", + "to": "user@example.com" + } + ] + }, + "tool_name": { + "description": "Name of the tool to execute", + "type": "string", + "examples": [ + "send_email" + ] + }, + "user_id": { + "description": "Optional. The user ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple users.", + "type": "string", + "examples": [ + "user_123" + ] + } + } + }, + "toolsExecuteToolResponse": { + "type": "object", + "properties": { + "data": { + "description": "Free-flowing JSON parameters for the tool execution", + "type": "object", + "examples": [ + { + "body": "Hello World", + "subject": "Hello", + "to": "user@example.com" + } + ] + }, + "execution_id": { + "description": "Unique identifier for the tool execution", + "type": "string", + "examples": [ + "123456789" + ] + } + } + }, + "ScalekitEvent": { + "type": "object", + "required": [ + "spec_version", + "id", + "type", + "occurred_at", + "environment_id", + "object" + ], + "properties": { + "spec_version": { + "type": "string", + "example": "1", + "description": "The webhook specification version", + "pattern": "^[0-9]+$" + }, + "id": { + "type": "string", + "pattern": "^evt_", + "example": "evt_1234567890abcdef", + "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")", + "minLength": 1, + "maxLength": 32 + }, + "type": { + "type": "string", + "example": "organization.created", + "description": "The event type", + "enum": [ + "organization.created", + "organization.updated", + "organization.deleted", + "organization.sso_created", + "organization.sso_deleted", + "organization.sso_enabled", + "organization.sso_disabled", + "user.signup", + "user.login", + "user.logout", + "user.organization_invitation", + "user.organization_membership_created", + "user.organization_membership_updated", + "user.organization_membership_deleted", + "organization.directory.user_created", + "organization.directory.user_updated", + "organization.directory.user_deleted", + "organization.directory.group_created", + "organization.directory.group_updated", + "organization.directory.group_deleted", + "organization.directory_enabled", + "organization.directory_disabled", + "role.created", + "role.updated", + "role.deleted", + "permission.created", + "permission.updated", + "permission.deleted" + ] + }, + "occurred_at": { + "type": "string", + "format": "date-time", + "description": "When the event occurred (ISO 8601 format)", + "example": "2024-01-01T00:00:00Z" + }, + "environment_id": { + "type": "string", + "pattern": "^env_", + "example": "env_1234567890abcdef", + "description": "The environment ID where the event occurred", + "minLength": 1, + "maxLength": 32 + }, + "organization_id": { + "type": "string", + "pattern": "^org_", + "example": "org_1234567890abcdef", + "description": "The organization ID (if applicable)", + "minLength": 1, + "maxLength": 32 + }, + "object": { + "type": "string", + "description": "The type of object that triggered the webhook", + "enum": [ + "Organization", + "Connection", + "Role", + "Directory", + "DirectoryUser", + "DirectoryGroup", + "Permission", + "OrgMembership", + "User" + ], + "example": "Organization" + }, + "data": { + "type": "object", + "description": "The event payload (structure varies by event type)", + "additionalProperties": true, + "example": { + "id": "org_1234567890abcdef", + "name": "Example Organization", + "created_at": "2024-01-01T00:00:00Z" + } + }, + "display_name": { + "type": "string", + "description": "Human-readable display name for the event", + "example": "Organization Created", + "minLength": 1, + "maxLength": 200 + } + } + } + } + } +} \ No newline at end of file diff --git a/public/api/agentkit.scalar.yaml b/public/api/agentkit.scalar.yaml new file mode 100644 index 000000000..9ed52efb6 --- /dev/null +++ b/public/api/agentkit.scalar.yaml @@ -0,0 +1,1428 @@ +openapi: 3.1.1 +info: + title: AgentKit APIs + description: | + # Overview + + The AgentKit API gives your AI agents authenticated access to third-party apps — sending emails, reading calendars, creating tickets, querying databases, and more. Your agent calls a tool; Scalekit handles the OAuth flow, token storage, and API call. + + **Base URLs:** + + ``` + https://{your-subdomain}.scalekit.dev (Development) + https://{your-subdomain}.scalekit.com (Production) + ``` + + ## Quickstart + + ### 1. Get an access token + + Use your API credentials from the [Scalekit Dashboard](https://app.scalekit.com) → **Developers → Settings → API Credentials**. + + ```sh + curl -X POST https:///oauth/token \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'client_id={client_id}' \ + -d 'client_secret={client_secret}' \ + -d 'grant_type=client_credentials' + ``` + + ### 2. List connected accounts + + ```sh + curl https:///api/v1/connected_accounts \ + -H 'Authorization: Bearer {access_token}' + ``` + + ### 3. Execute a tool on behalf of a user + + ```sh + curl -X POST https:///api/v1/execute_tool \ + -H 'Authorization: Bearer {access_token}' \ + -H 'Content-Type: application/json' \ + -d '{ + "connected_account_id": "{connected_account_id}", + "tool_name": "gmail_fetch_emails", + "tool_input": { "max_results": 5 } + }' + ``` + + ## SDKs + + ```sh + npm install @scalekit-sdk/node # Node.js + pip install scalekit-sdk-python # Python + ``` + + For the full product guide, see the [AgentKit documentation](https://docs.scalekit.com/agentkit/quickstart/). + + --- + + Looking for SSO, SCIM, directory sync, or user management APIs? See the [SaaSKit API reference](https://docs.scalekit.com/saaskit/apis/). For the complete endpoint list across both products, see [All APIs](https://docs.scalekit.com/apis/). + contact: + name: Scalekit Inc + url: https://scalekit.com + email: support@scalekit.com + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0 + version: 1.0.0 +servers: + - url: https://$SCALEKIT_ENVIRONMENT_URL +security: + - oauth2: [] +tags: + - description: Manage connected accounts for third-party integrations and OAuth connections. Connected accounts represent authenticated access to external services like Google, Notion, Slack, and other applications. + name: Connected Accounts +externalDocs: + description: AgentKit Docs + url: https://docs.scalekit.com/agentkit/quickstart/ +paths: + /api/v1/connected_accounts: + get: + description: Retrieves a paginated list of connected accounts for third-party integrations. Filter by organization, user, connector type, provider, or identifier. Returns OAuth tokens, API keys, and connection status for each account. Use pagination tokens to navigate through large result sets. + tags: + - Connected Accounts + summary: List connected accounts + operationId: ConnectedAccountService_ListConnectedAccounts + parameters: + - schema: + type: string + description: Filter by organization ID. Returns only connected accounts associated with this organization. + name: organization_id + in: query + - schema: + type: string + description: Filter by user ID. Returns only connected accounts associated with this user. + name: user_id + in: query + - schema: + type: string + description: Filter by connector type (e.g., 'notion', 'slack', 'google'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed. + name: connector + in: query + - schema: + type: string + description: Filter by account identifier. The unique identifier for the connected account within the third-party service (e.g., email address, workspace ID). + name: identifier + in: query + - schema: + type: string + description: Filter by OAuth provider. The authentication provider name such as 'google', 'microsoft', 'github', etc. + name: provider + in: query + - schema: + type: integer + format: int64 + description: Maximum number of connected accounts to return per page. Must be between 0 and 100. Default is typically 10. + name: page_size + in: query + - schema: + type: string + description: Pagination token from a previous response. Use the next_page_token value from ListConnectedAccountsResponse to fetch the next page. + name: page_token + in: query + - schema: + type: string + description: Text search query to filter connected accounts by name, identifier, or other searchable fields. Case-insensitive. + name: query + in: query + responses: + '200': + description: Successfully retrieved the list of connected accounts with their authentication details and status + content: + application/json: + schema: + $ref: '#/components/schemas/connected_accountsListConnectedAccountsResponse' + '400': + description: Invalid request - occurs when query parameters are malformed or validation fails + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + put: + description: Updates authentication credentials and configuration for an existing connected account. Modify OAuth tokens, refresh tokens, access scopes, or API configuration settings. Specify the account by ID, or by combination of organization/user, connector, and identifier. Returns the updated account with new token expiry and status information. + tags: + - Connected Accounts + summary: Update connected account credentials + operationId: ConnectedAccountService_UpdateConnectedAccount + responses: + '200': + description: Connected account updated successfully with new credentials or configuration + content: + application/json: + schema: + $ref: '#/components/schemas/connected_accountsUpdateConnectedAccountResponse' + '400': + description: Invalid request - missing required fields, invalid authorization details, or validation failed + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + '404': + description: Connected account not found - the specified account does not exist + content: + application/json: + schema: {} + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/connected_accountsUpdateConnectedAccountRequest' + required: true + post: + description: Creates a new connected account with OAuth tokens or API credentials for third-party service integration. Supply authorization details including access tokens, refresh tokens, scopes, and optional API configuration. The account can be scoped to an organization or user. Returns the created account with its unique identifier and authentication status. + tags: + - Connected Accounts + summary: Create a connected account + operationId: ConnectedAccountService_CreateConnectedAccount + responses: + '201': + description: Connected account created successfully with authentication credentials stored securely + content: + application/json: + schema: + $ref: '#/components/schemas/connected_accountsCreateConnectedAccountResponse' + '400': + description: Invalid request - missing required fields, invalid authorization details, or validation failed + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + '409': + description: Conflict - connected account with the same identifier already exists + content: + application/json: + schema: {} + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/connected_accountsCreateConnectedAccountRequest' + required: true + /api/v1/connected_accounts/auth: + get: + description: Retrieves complete authentication details for a connected account including OAuth tokens, refresh tokens, scopes, and API configuration. Query by account ID or by combination of organization/user, connector, and identifier. Returns sensitive credential information - use appropriate access controls. + tags: + - Connected Accounts + summary: Get connected account auth credentials + operationId: ConnectedAccountService_GetConnectedAccountAuth + parameters: + - schema: + type: string + description: Organization ID for the connector + name: organization_id + in: query + - schema: + type: string + description: User ID for the connector + name: user_id + in: query + - schema: + type: string + description: Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed. + name: connector + in: query + - schema: + type: string + description: The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + name: identifier + in: query + - schema: + type: string + description: Unique identifier for the connected account + name: id + in: query + responses: + '200': + description: Successfully retrieved connected account with full authentication details + content: + application/json: + schema: + $ref: '#/components/schemas/connected_accountsGetConnectedAccountByIdentifierResponse' + '400': + description: Invalid request - missing required query parameters + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + '404': + description: Connected account not found - no account matches the specified criteria + content: + application/json: + schema: {} + /api/v1/connected_accounts/details: + get: + description: Returns metadata for a connected account including status, connector type, provider, and configuration without exposing stored authorization credentials. Look up by account ID, or by a combination of organization (or user), connector, and external identifier. + tags: + - Connected Accounts + summary: Get connected account metadata + operationId: ConnectedAccountService_GetConnectedAccountDetails + parameters: + - schema: + type: string + description: Organization ID for the connector + name: organization_id + in: query + - schema: + type: string + description: User ID for the connector + name: user_id + in: query + - schema: + type: string + description: Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed. + name: connector + in: query + - schema: + type: string + description: The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + name: identifier + in: query + - schema: + type: string + description: Unique identifier for the connected account + name: id + in: query + responses: + '200': + description: Successfully retrieved connected account details + content: + application/json: + schema: + $ref: '#/components/schemas/connected_accountsGetConnectedAccountByIdentifierResponse' + '400': + description: Invalid request - missing required query parameters + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + '404': + description: Connected account not found - no account matches the specified criteria + content: + application/json: + schema: {} + /api/v1/connected_accounts/magic_link: + post: + description: Creates a time-limited magic link for connecting or re-authorizing a third-party account. The link directs users to the OAuth authorization flow for the specified connector. Returns the generated link URL and expiration timestamp. Links typically expire after a short duration for security. + tags: + - Connected Accounts + summary: Generate authentication magic link + operationId: ConnectedAccountService_GetMagicLinkForConnectedAccount + responses: + '200': + description: Magic link generated successfully with authorization URL and expiry time + content: + application/json: + schema: + $ref: '#/components/schemas/connected_accountsGetMagicLinkForConnectedAccountResponse' + '400': + description: Invalid request - missing required parameters or invalid connector + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/connected_accountsGetMagicLinkForConnectedAccountRequest' + required: true + /api/v1/connected_accounts/user/verify: + post: + description: Confirms the user assertion and activates the connected account after the user completes third-party OAuth. Called by the B2B app server with auth_request_id and identifier. Validates that the asserted identifier matches the one stored on the auth request and promotes pending tokens to live. + tags: + - Connected Accounts + summary: Verify connected account user + operationId: ConnectedAccountService_VerifyConnectedAccountUser + responses: + '200': + description: Verification successful; connected account is now ACTIVE + content: + application/json: + schema: + $ref: '#/components/schemas/connected_accountsVerifyConnectedAccountUserResponse' + '400': + description: Invalid request - missing or malformed fields + content: + application/json: + schema: {} + '401': + description: Unauthorized - invalid or missing access token + content: + application/json: + schema: {} + '403': + description: Forbidden - identifier mismatch + content: + application/json: + schema: {} + '404': + description: Not found - no pending flow for the given auth_request_id or already consumed + content: + application/json: + schema: {} + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/connected_accountsVerifyConnectedAccountUserRequest' + required: true + /api/v1/connected_accounts:delete: + post: + description: Permanently removes a connected account and revokes all associated authentication credentials. Identify the account by ID, or by combination of organization/user, connector, and identifier. This action cannot be undone. All OAuth tokens and API keys for this account will be invalidated. + tags: + - Connected Accounts + summary: Delete a connected account + operationId: ConnectedAccountService_DeleteConnectedAccount + responses: + '200': + description: Connected account deleted successfully and all credentials revoked + content: + application/json: + schema: {} + '400': + description: Invalid request - malformed parameters or validation failed + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + '404': + description: Connected account not found - the specified account does not exist + content: + application/json: + schema: {} + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/connected_accountsDeleteConnectedAccountRequest' + required: true + /api/v1/connected_accounts:search: + get: + description: Search for connected accounts in your environment using a text query that matches against identifiers, providers, or connectors. The search performs case-insensitive matching across account details. Returns paginated results with account status and authentication type information. + tags: + - Connected Accounts + summary: Search connected accounts + operationId: ConnectedAccountService_SearchConnectedAccounts + parameters: + - schema: + type: string + description: Search term to match against connected account identifiers, providers, or connectors. Must be at least 3 characters. Case insensitive. + name: query + in: query + - schema: + type: integer + format: int64 + description: Maximum number of connected accounts to return per page. Value must be between 1 and 30. + name: page_size + in: query + - schema: + type: string + description: Token from a previous response for pagination. Provide this to retrieve the next page of results. + name: page_token + in: query + - schema: + type: string + description: Connection ID to filter connected accounts + name: connection_id + in: query + responses: + '200': + description: Successfully retrieved matching connected accounts with pagination support + content: + application/json: + schema: + $ref: '#/components/schemas/connected_accountsSearchConnectedAccountsResponse' + '400': + description: Invalid request - query parameter is too short (minimum 3 characters) or validation failed + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + /api/v1/execute_tool: + post: + description: Executes a tool action using authentication credentials from a connected account. Specify the tool by name and provide required parameters as JSON. The connected account can be identified by ID, or by combination of organization/user, connector, and identifier. Returns the execution result data and a unique execution ID for tracking. Use this endpoint to perform actions like sending emails, creating calendar events, or managing resources in external services. + tags: + - Connected Accounts + summary: Execute a tool using a connected account + operationId: ToolService_ExecuteTool + responses: + '200': + description: Tool executed successfully with result data and execution ID + content: + application/json: + schema: + $ref: '#/components/schemas/toolsExecuteToolResponse' + '400': + description: Invalid request - occurs when tool name is missing, parameters are malformed, or tool definition validation fails + content: + application/json: + schema: {} + '401': + description: Authentication required - missing or invalid access token + content: + application/json: + schema: {} + '404': + description: Tool or connected account not found - occurs when the specified tool name or connected account does not exist + content: + application/json: + schema: {} + '500': + description: Tool execution failed - occurs when the external service returns an error or the tool encounters a runtime exception + content: + application/json: + schema: {} + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/toolsExecuteToolRequest' + required: true +webhooks: + connected_account.created: + post: + summary: Connected Account Created + description: Triggered when a new connected account is created + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_101531404017336586 + type: connected_account.created + object: ConnectedAccount + occurred_at: '2025-12-01T10:23:52.702980847Z' + environment_id: env_88640229614813449 + data: + authorization_type: OAUTH + connection_id: conn_100668583155073286 + id: ca_101531404000559370 + identifier: Bruce + provider: CANVA + status: PENDING_AUTH + responses: + '200': + description: Webhook received successfully + connected_account.updated: + post: + summary: Connected Account Updated + description: Triggered when a connected account is updated + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_101652975398683158 + type: connected_account.updated + object: ConnectedAccount + occurred_at: '2025-12-02T06:31:34.895815554Z' + environment_id: env_88640229614813449 + display_name: Connected account updated + data: + authorization_type: OAUTH + connection_id: conn_100510054016352776 + id: ca_100510623602835982 + identifier: Pranesh + provider: SUPABASE + status: PENDING_AUTH + responses: + '200': + description: Webhook received successfully + connected_account.deleted: + post: + summary: Connected Account Deleted + description: Triggered when a connected account is deleted + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_101653010731500290 + type: connected_account.deleted + object: ConnectedAccount + occurred_at: '2025-12-02T06:31:55.954027187Z' + environment_id: env_88640229614813449 + display_name: connected account deleted + data: + authorization_type: OAUTH + connection_id: conn_101644109747323155 + id: ca_101649788113519113 + identifier: Clark + last_used_at: '2025-12-02T06:00:01.374253Z' + provider: GOOGLE_ADS + status: ACTIVE + token_expires_at: '2025-12-02T06:59:57.237447Z' + responses: + '200': + description: Webhook received successfully + connected_account.magic_link_generated: + post: + summary: Connected Account Magic Link Generated + description: Triggered when a magic link is generated for OAuth flow + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_101652975398683158 + type: connected_account.magic_link_generated + object: ConnectedAccount + occurred_at: '2025-12-02T06:31:34.895815554Z' + environment_id: env_88640229614813448 + data: + authorization_type: OAUTH + connection_id: conn_100510054016352776 + id: ca_100510623602835982 + identifier: Pranesh + provider: SUPABASE + status: PENDING_AUTH + responses: + '200': + description: Webhook received successfully + connected_account.oauth_tokens_fetched: + post: + summary: Connected Account OAuth Tokens Fetched + description: Triggered when OAuth tokens are successfully fetched + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_101649795042509316 + type: connected_account.oauth_tokens_fetched + object: ConnectedAccount + occurred_at: '2025-12-02T05:59:59.250126407Z' + environment_id: env_88640229614813449 + data: + authorization_type: OAUTH + connection_id: conn_101644109747323155 + id: ca_101649788113519113 + identifier: Clark + provider: GOOGLE_ADS + status: ACTIVE + token_expires_at: '2025-12-02T06:59:57.237447778Z' + responses: + '200': + description: Webhook received successfully + connected_account.token_refresh_succeeded: + post: + summary: Connected Account Token Refresh Succeeded + description: Triggered when token refresh succeeds + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_101651946317808143 + type: connected_account.token_refresh_succeeded + object: ConnectedAccount + occurred_at: '2025-12-02T06:21:21.517480021Z' + environment_id: env_88640229614813449 + data: + authorization_type: OAUTH + connection_id: conn_101644109747323155 + id: ca_101644170698948883 + identifier: Pranesh + last_used_at: '2025-12-02T06:21:21.393723232Z' + provider: GOOGLE_ADS + status: ACTIVE + token_expires_at: '2025-12-02T07:21:20.508197312Z' + responses: + '200': + description: Webhook received successfully + connected_account.token_refresh_failed: + post: + summary: Connected Account Token Refresh Failed + description: Triggered when token refresh fails + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_101649795042509316 + type: connected_account.token_refresh_failed + object: ConnectedAccount + occurred_at: '2025-12-02T05:59:59.250126407Z' + environment_id: env_88640229614813445 + data: + authorization_type: OAUTH + connection_id: conn_101644109747323155 + id: ca_101649788113519113 + identifier: Clark + provider: GOOGLE_ADS + status: ACTIVE + token_expires_at: '2025-12-02T06:59:57.237447778Z' + responses: + '200': + description: Webhook received successfully + connected_account.oauth_succeeded: + post: + summary: Connected Account OAuth Succeeded + description: Triggered when OAuth authentication succeeds + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_101649484227871236 + type: connected_account.oauth_succeeded + object: ConnectedAccount + occurred_at: '2025-12-02T05:56:53.994604757Z' + environment_id: env_88640229614813449 + data: + authorization_type: OAUTH + connection_id: conn_101644109747323155 + id: ca_101649474950005257 + identifier: Bruce + provider: GOOGLE_ADS + status: ACTIVE + token_expires_at: '2025-12-02T06:56:52.976081699Z' + responses: + '200': + description: Webhook received successfully +components: + securitySchemes: + oauth2: + type: oauth2 + flows: + clientCredentials: + tokenUrl: https://$SCALEKIT_ENVIRONMENT_URL/oauth/token + scopes: + '': No scope required for client credentials flow + schemas: + connected_accountsConnectorType: + description: |- + - OAUTH: OAuth 2.0 authorization with access and refresh tokens + - API_KEY: Static API key authentication + - BASIC_AUTH: HTTP Basic Authentication (username/password) + - BEARER_TOKEN: Bearer token authentication + - CUSTOM: Custom authentication mechanism + - BASIC: Basic authentication (alias) + - OAUTH_M2M: OAuth 2.0 client credentials (machine-to-machine) + - TRELLO_OAUTH1: Trello token-based OAuth1-style browser authorization + - GOOGLE_DWD: Google Domain-Wide Delegation + type: string + title: Type of authentication mechanism used for the connected account + enum: + - OAUTH + - API_KEY + - BASIC_AUTH + - BEARER_TOKEN + - CUSTOM + - BASIC + - OAUTH_M2M + - TRELLO_OAUTH1 + - GOOGLE_DWD + connected_accountsConnectorStatus: + description: |- + - ACTIVE: Account is connected and credentials are valid + - EXPIRED: Access token has expired and needs refresh + - PENDING_AUTH: Account awaiting user authorization (re-auth initiated) + - PENDING_VERIFICATION: OAuth complete; awaiting user identity verification + before activation + - DISCONNECTED: Account has been manually disconnected + type: string + title: Status of a connected account indicating its current state + enum: + - ACTIVE + - EXPIRED + - PENDING_AUTH + - PENDING_VERIFICATION + - DISCONNECTED + connected_accountsConnectedAccountForList: + type: object + title: Connected account summary for list operations - excludes sensitive authorization details + properties: + authorization_type: + description: Authorization mechanism type. + $ref: '#/components/schemas/connected_accountsConnectorType' + connection_id: + description: Parent connection configuration reference. + type: string + examples: + - conn_24834495392086178 + connector: + description: Connector identifier. + type: string + examples: + - notion + id: + description: Unique connected account identifier. + type: string + examples: + - ca_24834495392086178 + identifier: + description: The unique identifier for this account in the third-party service. + type: string + examples: + - user@example.com + last_used_at: + description: Last usage timestamp. + type: string + format: date-time + examples: + - '2024-03-20T14:30:00Z' + provider: + description: OAuth provider name (e.g., 'google', 'microsoft'). + type: string + examples: + - google + status: + description: Current connection status. + $ref: '#/components/schemas/connected_accountsConnectorStatus' + token_expires_at: + description: Token expiration timestamp. + type: string + format: date-time + examples: + - '2024-12-31T23:59:59Z' + updated_at: + description: Last modification timestamp. + type: string + format: date-time + examples: + - '2024-03-20T15:04:05Z' + connected_accountsListConnectedAccountsResponse: + type: object + properties: + connected_accounts: + description: List of connected accounts matching the filter criteria. Excludes sensitive authorization details for security. + type: array + items: + type: object + $ref: '#/components/schemas/connected_accountsConnectedAccountForList' + next_page_token: + description: Pagination token for retrieving the next page. Empty if this is the last page. Pass this value to page_token in the next request. + type: string + examples: + - eyJvZmZzZXQiOjIwfQ== + prev_page_token: + description: Pagination token for retrieving the previous page. Empty if this is the first page. Pass this value to page_token to go back. + type: string + examples: + - eyJvZmZzZXQiOjB9 + total_size: + description: Total count of connected accounts matching the filter criteria across all pages. Use for calculating pagination. + type: integer + format: int64 + examples: + - 100 + connected_accountsGoogleDWDAuth: + description: |- + Google Domain-Wide Delegation authentication — used for GOOGLE_DWD connections. + Send only subject in requests; access_token, scopes, and token_expires_at are response-only. + type: object + properties: + access_token: + description: OAuth access token acquired via the jwt-bearer grant. Present in responses only. + type: string + readOnly: true + examples: + - ya29.a0AfH6SMBx... + scopes: + description: OAuth scopes granted to this token. Present in responses only. + type: array + items: + type: string + readOnly: true + examples: + - - openid + - https://www.googleapis.com/auth/userinfo.email + subject: + description: Email address of the Google Workspace user to impersonate via Domain-Wide Delegation. + type: string + examples: + - user@example.com + token_expires_at: + description: When the access token expires. Present in responses only. + type: string + format: date-time + readOnly: true + connected_accountsOauthToken: + type: object + title: OAuth 2.0 access and refresh tokens with scopes + properties: + access_token: + description: OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + type: string + examples: + - ya29.a0AfH6SMBx... + domain: + description: Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + type: string + examples: + - example.com + refresh_token: + description: OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + type: string + examples: + - 1//0gHJxZ-Lb2... + scopes: + description: List of granted OAuth scopes defining the permissions and access levels for this connection. + type: array + items: + type: string + examples: + - - https://www.googleapis.com/auth/drive.readonly + - https://www.googleapis.com/auth/userinfo.email + connected_accountsStaticAuth: + type: object + title: Static authentication credentials for API keys, bearer tokens, or basic auth + properties: + details: + description: Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + type: object + examples: + - api_key: sk_live_... + api_secret: ... + connected_accountsAuthorizationDetails: + type: object + title: Authentication credentials container supporting multiple auth types + properties: + google_dwd: + title: Google Domain-Wide Delegation credentials + $ref: '#/components/schemas/connected_accountsGoogleDWDAuth' + oauth_token: + title: OAuth 2.0 credentials + $ref: '#/components/schemas/connected_accountsOauthToken' + static_auth: + title: Static authentication credentials + $ref: '#/components/schemas/connected_accountsStaticAuth' + v1connected_accountsUpdateConnectedAccount: + type: object + title: Payload for updating an existing connected account - all fields optional + properties: + api_config: + description: Updated JSON configuration for API-specific settings. Merges with existing configuration - only provided fields are modified. + type: object + examples: + - rate_limit: 2000 + timeout: 60 + authorization_details: + description: Updated authentication credentials. Provide new OAuth tokens (e.g., after refresh) or updated static auth details. Only included fields will be modified. + $ref: '#/components/schemas/connected_accountsAuthorizationDetails' + examples: + - oauth_token: + access_token: ya29.new_token... + refresh_token: 1//0g... + scopes: + - email + - profile + - calendar + connected_accountsUpdateConnectedAccountRequest: + type: object + properties: + connected_account: + description: Details of the connected account to update + $ref: '#/components/schemas/v1connected_accountsUpdateConnectedAccount' + examples: + - authorization_details: + oauth_token: + access_token: ... + refresh_token: ... + scopes: + - read + - write + authorization_type: OAUTH2 + connector: + description: Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed. + type: string + examples: + - notion + id: + description: Unique identifier for the connected account to update + type: string + examples: + - ca_123 + identifier: + description: The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + type: string + examples: + - user@example.com + organization_id: + description: Organization ID for the connector + type: string + examples: + - org_121312434123312 + user_id: + description: User ID for the connector + type: string + examples: + - user_121312434123312 + connected_accountsConnectedAccount: + type: object + properties: + api_config: + description: Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. + type: object + examples: + - base_url: https://api.custom-domain.com + rate_limit: 1000 + timeout: 30 + authorization_details: + description: Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details. + $ref: '#/components/schemas/connected_accountsAuthorizationDetails' + authorization_type: + description: Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. + $ref: '#/components/schemas/connected_accountsConnectorType' + connection_id: + description: Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. + type: string + examples: + - conn_24834495392086178 + connector: + description: Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to. + type: string + examples: + - notion + id: + description: Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca_'. + type: string + examples: + - ca_24834495392086178 + identifier: + description: The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier. + type: string + examples: + - user@example.com + last_used_at: + description: Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. + type: string + format: date-time + examples: + - '2024-03-20T14:30:00Z' + provider: + description: OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection. + type: string + examples: + - google + status: + description: Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. + $ref: '#/components/schemas/connected_accountsConnectorStatus' + token_expires_at: + description: Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. + type: string + format: date-time + examples: + - '2024-12-31T23:59:59Z' + updated_at: + description: Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. + type: string + format: date-time + examples: + - '2024-03-20T15:04:05Z' + connected_accountsUpdateConnectedAccountResponse: + type: object + properties: + connected_account: + description: The updated connected account with refreshed credentials, new token expiry, and modified configuration settings. + $ref: '#/components/schemas/connected_accountsConnectedAccount' + v1connected_accountsCreateConnectedAccount: + type: object + title: Payload for creating a new connected account - authorization details are optional + properties: + api_config: + description: Optional JSON configuration for connector-specific API settings such as rate limits, custom API endpoints, timeouts, or feature flags. + type: object + examples: + - base_url: https://api.custom-domain.com + rate_limit: 1000 + timeout: 30 + authorization_details: + description: Optional authentication credentials for the connected account. Include OAuth tokens (access_token, refresh_token, scopes) or static auth details (API keys, bearer tokens). Can be provided later via update. + $ref: '#/components/schemas/connected_accountsAuthorizationDetails' + examples: + - oauth_token: + access_token: ya29.a0... + refresh_token: 1//0g... + scopes: + - email + - profile + connected_accountsCreateConnectedAccountRequest: + type: object + properties: + connected_account: + description: Details of the connected account to create + $ref: '#/components/schemas/v1connected_accountsCreateConnectedAccount' + examples: + - authorization_details: + oauth_token: + access_token: ... + refresh_token: ... + scopes: + - read + - write + authorization_type: OAUTH2 + connector: + description: Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed. + type: string + examples: + - notion + identifier: + description: The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + type: string + examples: + - user@example.com + organization_id: + description: Organization ID for the connector + type: string + examples: + - org_121312434123312 + user_id: + description: User ID for the connector + type: string + examples: + - user_121312434123312 + connected_accountsCreateConnectedAccountResponse: + type: object + properties: + connected_account: + description: The newly created connected account with its unique identifier, status, and complete authorization details including access tokens. + $ref: '#/components/schemas/connected_accountsConnectedAccount' + connected_accountsGetConnectedAccountByIdentifierResponse: + type: object + properties: + connected_account: + description: The connected account with complete details including sensitive authorization credentials (access tokens, refresh tokens, scopes). Handle with appropriate access controls. + $ref: '#/components/schemas/connected_accountsConnectedAccount' + connected_accountsGetMagicLinkForConnectedAccountRequest: + type: object + properties: + connector: + description: Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed. + type: string + examples: + - notion + id: + description: Unique identifier for the connected account + type: string + examples: + - ca_123 + identifier: + description: The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + type: string + examples: + - user@example.com + organization_id: + description: Organization ID for the connector + type: string + examples: + - org_121312434123312 + state: + description: Optional opaque state value. State added to the user verify redirect URL query params to validate the user verification + type: string + examples: + - QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY= + user_id: + description: User ID for the connector + type: string + examples: + - user_121312434123312 + user_verify_url: + description: B2B app's user verify redirect URL + type: string + examples: + - https://app.yourapp.com/user/verify/callback + connected_accountsGetMagicLinkForConnectedAccountResponse: + type: object + properties: + expiry: + description: Expiry timestamp for the authentication link + type: string + format: date-time + examples: + - '2024-03-20T15:04:05Z' + link: + description: Authentication link for the connector + type: string + examples: + - https://notion.com/oauth/authorize?client_id=... + connected_accountsVerifyConnectedAccountUserRequest: + type: object + required: + - auth_request_id + - identifier + properties: + auth_request_id: + description: Auth request ID as base64url-encoded opaque token from the user verify redirect URL query params + type: string + examples: + - QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY= + identifier: + description: Current logged in user's connected account identifier + type: string + examples: + - user@example.com + connected_accountsVerifyConnectedAccountUserResponse: + type: object + properties: + post_user_verify_redirect_url: + description: URL to redirect the user to after successful verification + type: string + examples: + - https://env1.example.com/connect/success + connected_accountsDeleteConnectedAccountRequest: + type: object + properties: + connector: + description: Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed. + type: string + examples: + - notion + id: + description: Unique identifier for the connected account to delete + type: string + examples: + - ca_123 + identifier: + description: The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + type: string + examples: + - user@example.com + organization_id: + description: Organization ID for the connector + type: string + examples: + - org_121312434123312 + user_id: + description: User ID for the connector + type: string + examples: + - user_121312434123312 + connected_accountsSearchConnectedAccountsResponse: + type: object + properties: + connected_accounts: + description: List of connected accounts matching the search query. Excludes sensitive authorization details. + type: array + items: + type: object + $ref: '#/components/schemas/connected_accountsConnectedAccountForList' + next_page_token: + description: Pagination token for the next page. Empty if this is the last page. + type: string + examples: + - eyJvZmZzZXQiOjMwfQ== + prev_page_token: + description: Pagination token for the previous page. Empty if this is the first page. + type: string + examples: + - eyJvZmZzZXQiOjB9 + total_size: + description: Total count of accounts matching the search query across all pages. + type: integer + format: int64 + examples: + - 100 + toolsExecuteToolRequest: + type: object + properties: + agent_run_id: + description: Optional. Customer-supplied identifier grouping multiple tool calls into a single agent run. Useful for correlating logs across an agentic workflow. + type: string + examples: + - run_abc123 + connected_account_id: + description: Optional. The unique ID of the connected account. Use this to directly identify the connected account instead of using identifier + connector combination. + type: string + examples: + - ca_123 + connector: + description: Optional. The name of the connector/provider (e.g., 'Google Workspace', 'Slack', 'Notion'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed. Use this in combination with identifier to identify the connected account. + type: string + examples: + - Google Workspace + identifier: + description: Optional. The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). Use this in combination with connector to identify the connected account. + type: string + examples: + - user@example.com + organization_id: + description: Optional. The organization ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple organizations. + type: string + examples: + - org_123 + params: + description: JSON object containing the parameters required for tool execution. The structure depends on the specific tool being executed. + type: object + examples: + - body: Hello World + subject: Hello + to: user@example.com + tool_name: + description: Name of the tool to execute + type: string + examples: + - send_email + user_id: + description: Optional. The user ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple users. + type: string + examples: + - user_123 + toolsExecuteToolResponse: + type: object + properties: + data: + description: Free-flowing JSON parameters for the tool execution + type: object + examples: + - body: Hello World + subject: Hello + to: user@example.com + execution_id: + description: Unique identifier for the tool execution + type: string + examples: + - '123456789' + ScalekitEvent: + type: object + required: + - spec_version + - id + - type + - occurred_at + - environment_id + - object + properties: + spec_version: + type: string + example: '1' + description: The webhook specification version + pattern: ^[0-9]+$ + id: + type: string + pattern: ^evt_ + example: evt_1234567890abcdef + description: Unique identifier for the webhook event (must be prefixed with "evt_") + minLength: 1 + maxLength: 32 + type: + type: string + example: organization.created + description: The event type + enum: + - organization.created + - organization.updated + - organization.deleted + - organization.sso_created + - organization.sso_deleted + - organization.sso_enabled + - organization.sso_disabled + - user.signup + - user.login + - user.logout + - user.organization_invitation + - user.organization_membership_created + - user.organization_membership_updated + - user.organization_membership_deleted + - organization.directory.user_created + - organization.directory.user_updated + - organization.directory.user_deleted + - organization.directory.group_created + - organization.directory.group_updated + - organization.directory.group_deleted + - organization.directory_enabled + - organization.directory_disabled + - role.created + - role.updated + - role.deleted + - permission.created + - permission.updated + - permission.deleted + occurred_at: + type: string + format: date-time + description: When the event occurred (ISO 8601 format) + example: '2024-01-01T00:00:00Z' + environment_id: + type: string + pattern: ^env_ + example: env_1234567890abcdef + description: The environment ID where the event occurred + minLength: 1 + maxLength: 32 + organization_id: + type: string + pattern: ^org_ + example: org_1234567890abcdef + description: The organization ID (if applicable) + minLength: 1 + maxLength: 32 + object: + type: string + description: The type of object that triggered the webhook + enum: + - Organization + - Connection + - Role + - Directory + - DirectoryUser + - DirectoryGroup + - Permission + - OrgMembership + - User + example: Organization + data: + type: object + description: The event payload (structure varies by event type) + additionalProperties: true + example: + id: org_1234567890abcdef + name: Example Organization + created_at: '2024-01-01T00:00:00Z' + display_name: + type: string + description: Human-readable display name for the event + example: Organization Created + minLength: 1 + maxLength: 200 diff --git a/public/api/saaskit.scalar.json b/public/api/saaskit.scalar.json new file mode 100644 index 000000000..e9ed39682 --- /dev/null +++ b/public/api/saaskit.scalar.json @@ -0,0 +1,12042 @@ +{ + "openapi": "3.1.1", + "info": { + "description": "# Overview\n\nThe Scalekit API is a RESTful API that enables you to manage organizations, users, and authentication settings. All requests must use HTTPS.\nAll API requests use the following base URLs:\n\n```\nhttps://{your-subdomain}.scalekit.dev (Development)\nhttps://{your-subdomain}.scalekit.com (Production)\nhttps://auth.yourapp.com (Custom domain)\n```\n\nScalekit operates two separate environments: Development and Production. Resources cannot be moved between environments.\n\n## Quickstart\n\nThe Scalekit API uses OAuth 2.0 Client Credentials for authentication.\n\nCopy your API credentials from the Scalekit dashboard's API Config section and set them as environment variables.\n\n```sh\nSCALEKIT_ENVIRONMENT_URL=''\nSCALEKIT_CLIENT_ID=''\nSCALEKIT_CLIENT_SECRET=''\n```\n\nGetting an access token\n\n1. Get your credentials from the [Scalekit Dashboard](https://app.scalekit.com)\n2. Request an access token:\n\n```sh\ncurl https:///oauth/token \\\n -X POST \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d 'client_id={client_id}' \\\n -d 'client_secret={client_secret}' \\\n -d 'grant_type=client_credentials'\n```\n\n3. Use the access token in API requests:\n\n```sh\ncurl https:///api/v1/organizations \\\n -H 'Content-Type: application/json' \\\n -H 'Authorization: Bearer {access_token}'\n```\n\nThe response includes an access token:\n\n```json\n{\n\t\"access_token\": \"eyJhbGciOiJSUzI1NiIsImtpZCI6InNua181Ok4OTEyMjU2NiIsInR5cCI6IkpXVCJ9...\",\n\t\"token_type\": \"Bearer\",\n\t\"expires_in\": 86399,\n\t\"scope\": \"openid\"\n}\n```\n\n## SDKs\n\nScalekit provides official SDKs for multiple programming languages. Check the changelog at GitHub repositories for the latest updates.\n\n### Node.js\n\n```sh\nnpm install @scalekit-sdk/node\n```\n\nCreate a new Scalekit client instance after initializing the environment variables\n\n```js\nimport { Scalekit } from \"@scalekit-sdk/node\";\n\nexport let scalekit = new Scalekit(\n\tprocess.env.SCALEKIT_ENVIRONMENT_URL,\n\tprocess.env.SCALEKIT_CLIENT_ID,\n\tprocess.env.SCALEKIT_CLIENT_SECRET\n);\n```\n\n[See the Node SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-node/releases)\n\n### Python\n\n```sh\npip install scalekit-sdk-python\n```\n\nCreate a new Scalekit client instance after initializing the environment variables.\n\n```py\nfrom scalekit import ScalekitClient\nimport os\n\nscalekit_client = ScalekitClient(\n os.environ.get('SCALEKIT_ENVIRONMENT_URL'),\n os.environ.get('SCALEKIT_CLIENT_ID'),\n os.environ.get('SCALEKIT_CLIENT_SECRET')\n)\n```\n\n[See the Python SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-python/releases)\n\n### Go\n\n```sh\ngo get -u github.com/scalekit-inc/scalekit-sdk-go\n```\n\nCreate a new Scalekit client instance after initializing the environment variables.\n\n```go\npackage main\n\nimport (\n \"os\"\n \"github.com/scalekit-inc/scalekit-sdk-go\"\n)\n\nscalekitClient := scalekit.NewScalekitClient(\n os.Getenv(\"SCALEKIT_ENVIRONMENT_URL\"),\n os.Getenv(\"SCALEKIT_CLIENT_ID\"),\n os.Getenv(\"SCALEKIT_CLIENT_SECRET\"),\n)\n```\n\n[See the Go SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-go/releases)\n\n### Java\n\n```gradle\n/* Gradle users - add the following to your dependencies in build file */\nimplementation \"com.scalekit:scalekit-sdk-java:2.0.11\"\n```\n\n```xml\n\n\n com.scalekit\n scalekit-sdk-java\n 2.0.11\n\n```\n\n[See the Java SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-java/releases)\n\n### Error handling\n\nThe API uses standard HTTP status codes:\n\n| Code | Description |\n| ----------- | -------------------- |\n| 200/201 | Success |\n| 400 | Invalid request |\n| 401 | Authentication error |\n| 404 | Resource not found |\n| 429 | Rate limit exceeded |\n| 500/501/504 | Server error |\n\nError responses include detailed information:\n\n```json\n{\n\t\"code\": 16,\n\t\"message\": \"Token empty\",\n\t\"details\": [\n\t\t{\n\t\t\t\"@type\": \"type.googleapis.com/scalekit.v1.errdetails.ErrorInfo\",\n\t\t\t\"error_code\": \"UNAUTHENTICATED\"\n\t\t}\n\t]\n}\n```\n", + "title": "Scalekit APIs", + "contact": { + "name": "Scalekit Inc", + "url": "https://scalekit.com", + "email": "support@scalekit.com" + }, + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0" + }, + "version": "1.0.0", + "x-scalar-sdk-installation": [ + { + "lang": "shell", + "description": "Set up OAuth 2.0 Client Credentials authentication to access Scalekit APIs. Includes credential configuration, token exchange, and authenticated API request examples.", + "source": "\n# 1. Obtain API Credentials\n# Get your credentials from the Scalekit dashboard\nexport SCALEKIT_ENVIRONMENT_URL=\"https://your-org.scalekit.dev\" # Your Scalekit environment URL\nexport SCALEKIT_CLIENT_ID=\"your_client_id\" # Your client ID\nexport SCALEKIT_CLIENT_SECRET=\"your_client_secret\" # Your client secret\n\n# 2. Exchange client credentials an OAuth 2.0 access token\nTOKEN_RESPONSE=$(curl -s -X POST \"${SCALEKIT_ENVIRONMENT_URL}/oauth/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"client_id=${SCALEKIT_CLIENT_ID}\" \\\n -d \"client_secret=${SCALEKIT_CLIENT_SECRET}\" \\\n -d \"grant_type=client_credentials\")\n\n# 3. Make Authenticated API Requests\ncurl -X GET \"${SCALEKIT_ENVIRONMENT_URL}/api/v1/organizations\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n -H \"Accept: application/json\"\n" + } + ] + }, + "servers": [ + { + "url": "https://$SCALEKIT_ENVIRONMENT_URL" + } + ], + "security": [ + { + "oauth2": [] + } + ], + "tags": [ + { + "description": "Organization represents a customer or a tenant of your product. This is the top level entity and all resources are mapped to this Organization object. Each organization is uniquely identified by `organization_id`.\n\n\n", + "name": "Organizations" + }, + { + "description": "Permission management for defining and controlling access to system resources. Create, retrieve, update, and delete granular permissions that represent specific actions users can perform. Permissions are the building blocks of role-based access control (RBAC) and can be assigned to roles to grant users the ability to perform specific operations. Use this service to define custom permissions for your application's unique access control requirements.", + "name": "Permissions" + }, + { + "description": "Comprehensive user management operations including user lifecycle, organization memberships, and invitation workflows. This service provides endpoints for creating, retrieving, updating, and deleting user accounts across your Scalekit environment. It supports both individual user operations and bulk operations for user administration, including user search, pagination, and metadata management. The service also handles user invitations and organization membership management.", + "name": "Users" + }, + { + "description": "Manage enterprise connections for your Scalekit environment. This service provides endpoints for retrieving, and updating connections.", + "name": "Connections" + }, + { + "description": "Directory management for viewing and controlling external identity provider connections in your Scalekit environment. This service provides endpoints for retrieving directory information, listing directories and their contents, and enabling or disabling directory synchronization.", + "name": "Directory" + }, + { + "description": "Role-based access control (RBAC) for defining and managing permissions in an environment. Create and update custom roles with explicit permissions, model role hierarchies through inheritance, view dependent roles, manage role-permission assignments, and list roles and permissions. Also provides a utility to count users assigned to a role.", + "name": "Roles" + }, + { + "description": "Comprehensive session management for user authentication and authorization. This service provides endpoints for retrieving session details, managing user sessions across devices, revoking individual sessions, and terminating all active sessions for a user. It supports session auditing, device tracking, and security monitoring with detailed session metadata including device information, IP geolocation, and activity timestamps.", + "name": "Sessions" + }, + { + "description": "Manage organization-level domains. Scalekit supports two domain types:\n\n- ORGANIZATION_DOMAIN: Used for SSO domain discovery. When a user signs in with a matching email domain, Scalekit routes them to the organization’s SSO provider and enforces SSO.\n- ALLOWED_EMAIL_DOMAIN: Used to mark trusted email domains for an organization. When a user signs in or signs up with a matching domain, Scalekit suggests the organization in the organization switcher (authentication-method agnostic).\n", + "name": "Domains" + }, + { + "description": "Endpoints for managing API client applications. API clients enable secure, automated interactions between software systems without human intervention. Each client is uniquely identified by a `client_id` and can be configured with authentication settings, redirect URIs, and security parameters. Use these endpoints to create, manage, and configure API clients for your API clients.", + "name": "API Auth", + "externalDocs": { + "url": "https://docs.scalekit.com/m2m/overview" + } + }, + { + "description": "Endpoints for sending and verifying passwordless authentication emails. These APIs allow users to authenticate without passwords by receiving a verification code or magic link in their email.", + "name": "Magic link & OTP" + }, + { + "description": "Endpoints for passkey-based authentication using WebAuthn/FIDO2 standards.", + "name": "Passkeys" + } + ], + "externalDocs": { + "description": "Scalekit Docs", + "url": "https://docs.scalekit.com/" + }, + "paths": { + "/api/v1/connections": { + "get": { + "description": "Retrieves a list of connections in the environment", + "tags": [ + "Connections" + ], + "summary": "List connections", + "operationId": "ConnectionService_ListConnections", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Filter connections by organization identifier", + "name": "organization_id", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Filter connections by email domain associated with the organization", + "name": "domain", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Filter connections by status. Use 'all' to include all connections regardless of status. Default behavior shows only active (completed and enabled) connections", + "name": "include", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved connections", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connectionsListConnectionsResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "// List connections by organization id\nconst connections = await scalekit.connection.listConnections(organizationId);\n\n// List connections by domain\nconst connections = await scalekit.connection.listConnectionsByDomain(domain);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "# List connections by organization id\nconnections = scalekit_client.connection.list_connections(\n organization_id\n)\n\n# List connections by domain\nresponse = scalekit_client.connection.list_connections_by_domain(domain=\"example.com\")" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "// List connections by organization id\nconnections, err := scalekitClient.Connection().ListConnections(\n ctx,\n organizationId\n)\n\n// List connections by domain\nconnections, err := scalekitClient.Connection().ListConnectionsByDomain(ctx, \n domain)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "// List connections by organization id\nListConnectionsResponse response = scalekitClient.connections(\n ).listConnections(organizationId);\n\n// List connections by domain\nListConnectionsResponse response = scalekitClient.connections(\n ).listConnectionsByDomain(\"your-domain.com\");" + } + ] + } + }, + "/api/v1/invites/organizations/{organization_id}/users/{id}/resend": { + "patch": { + "description": "Resends an invitation email to a user who has a pending or expired invitation in the specified organization. If the invitation has expired, a new invitation will be automatically created and sent. If the invitation is still valid, a reminder email will be sent instead. Use this endpoint when a user hasn't responded to their initial invitation and you need to send them a reminder or when the original invitation has expired. The invitation email includes a secure magic link that allows the user to complete their account setup and join the organization. Each resend operation increments the resent counter.", + "tags": [ + "Users" + ], + "summary": "Resend user invitation email", + "operationId": "UserService_ResendInvite", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization containing the pending invitation. Must start with 'org_' and be 1-32 characters long.", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "System-generated user ID of the user who has a pending invitation. Must start with 'usr_' and be 19-25 characters long.", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully resent the invitation email. Returns the updated invitation object with organization ID, user ID, membership status, timestamps, and resent count. If expired, a new invitation is created; otherwise, the existing one is resent.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/usersResendInviteResponse" + } + } + } + }, + "400": { + "description": "Invalid request — common causes include user ID or organization ID is invalid, full-stack authentication is disabled, user profile is missing, invite already accepted, or missing expiry time in user management settings.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/errdetailsErrorInfo" + } + } + } + }, + "404": { + "description": "Resource not found — the specified user, organization, membership, or invitation could not be found in the specified environment. Verify that all IDs are correct and that the resources exist before attempting to resend an invitation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/errdetailsErrorInfo" + } + } + } + }, + "500": { + "description": "Internal server error — an unexpected error occurred while processing the invitation resend request. This may be due to database connectivity issues, problems generating the secure magic link, email delivery service failures, or transaction errors during invitation processing. Contact support if the problem persists.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/errdetailsErrorInfo" + } + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserServiceResendInviteBody" + } + } + }, + "required": true + } + } + }, + "/api/v1/memberships/organizations/{organization_id}/users/{id}": { + "post": { + "description": "Adds an existing user to an organization and assigns them specific roles and permissions. Use this endpoint when you want to grant an existing user access to a particular organization. You can specify roles, metadata, and other membership details during the invitation process.", + "tags": [ + "Users" + ], + "summary": "Add existing user to organization", + "operationId": "UserService_CreateMembership", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the target organization. Must start with 'org_' and be 1-32 characters long.", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "System-generated user ID. Must start with 'usr_' (19-25 characters)", + "name": "id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "External system identifier from connected directories. Must be unique across the system", + "name": "external_id", + "in": "query" + }, + { + "schema": { + "type": "boolean" + }, + "description": "If true, sends an activation email to the user. Defaults to true.", + "name": "send_invitation_email", + "in": "query" + } + ], + "responses": { + "201": { + "description": "User successfully added to the organization. Returns details of the updated membership details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/usersCreateMembershipResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "import { ScalekitClient } from \"@scalekit-sdk/node\";\nconst scalekit = new ScalekitClient(\n\tprocess.env.SCALEKIT_ENV_URL,\n\tprocess.env.SCALEKIT_CLIENT_ID,\n\tprocess.env.SCALEKIT_CLIENT_SECRET\n);\nawait scalekit.user.createMembership(\"org_123\", \"usr_123\", {\n\troles: [\"admin\"],\n\tmetadata: {\n\t\tdepartment: \"engineering\",\n\t\tlocation: \"nyc-office\",\n\t},\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "from scalekit.v1.users.users_pb2 import CreateMembership\nfrom scalekit.v1.commons.commons_pb2 import Role\n\nmembership = CreateMembership(\n roles=[Role(name=\"admin\")],\n metadata={\"department\": \"engineering\", \"location\": \"nyc-office\"},\n)\nresp = scalekit_client.users.create_membership(\n organization_id=\"org_123\",\n user_id=\"usr_123\",\n membership=membership,\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "func main() {\n scalekitClient := scalekit.NewScalekitClient(\n os.Getenv(\"SCALEKIT_ENV_URL\"),\n os.Getenv(\"SCALEKIT_CLIENT_ID\"),\n os.Getenv(\"SCALEKIT_CLIENT_SECRET\"),\n )\n membership := &usersv1.CreateMembership{\n Roles: []*usersv1.Role{{Name: \"admin\"}},\n Metadata: map[string]string{\n \"department\": \"engineering\",\n \"location\": \"nyc-office\",\n },\n }\n resp, \n err := scalekitClient.User().CreateMembership(\n context.Background(), \"org_123\", \n \"usr_123\", membership, false)\n if err != nil {\n panic(err)\n }\n}" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "import com.scalekit.ScalekitClient;\nimport com.scalekit.api.UserClient;\nimport com.scalekit.grpc.scalekit.v1.users.*;\nScalekitClient scalekitClient = new ScalekitClient(\n System.getenv(\"SCALEKIT_ENV_URL\"),\n System.getenv(\"SCALEKIT_CLIENT_ID\"),\n System.getenv(\"SCALEKIT_CLIENT_SECRET\")\n);\nUserClient users = scalekitClient.users();\nCreateMembershipRequest membershipReq = CreateMemb\n ershipRequest.newBuilder()\n .setMembership(\n CreateMembership.newBuilder()\n .addRoles(Role.newBuilder(\n ).setName(\"admin\").build())\n .putMetadata(\"department\", \"engineering\")\n .putMetadata(\"location\", \"nyc-office\")\n .build())\n .build();\nCreateMembershipResponse res = users.\n createMembership(\"org_123\", \"usr_123\", \n membershipReq);" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Membership details to create. Required fields must be provided.", + "$ref": "#/components/schemas/v1usersCreateMembership" + } + } + }, + "required": true + } + }, + "delete": { + "description": "Removes a user from an organization by user ID or external ID. If the user has no memberships left and cascade is true, the user is also deleted. This action is irreversible and may also remove related group memberships.", + "tags": [ + "Users" + ], + "summary": "Delete organization membership for user", + "operationId": "UserService_DeleteMembership", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique organization identifier. Must start with 'org_' and be 1-32 characters long", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "System-generated user ID. Must start with 'usr_' (19-25 characters)", + "name": "id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "External system identifier from connected directories. Must match existing records", + "name": "external_id", + "in": "query" + } + ], + "responses": { + "200": { + "description": "User successfully marked for deletion. No content returned", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-codeSamples": [ + { + "label": "Python SDK", + "lang": "python", + "source": "response = scalekit_client.users.delete_membership(\n organization_id=org_id,user_id=user_id\n)" + } + ] + }, + "patch": { + "description": "Updates a user's membership details within an organization by user ID or external ID. You can update roles and membership metadata.", + "tags": [ + "Users" + ], + "summary": "Update organization membership for user", + "operationId": "UserService_UpdateMembership", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization containing the membership. Must start with 'org_' and be 1-32 characters long.", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "System-generated user ID. Must start with 'usr_' and be 19-25 characters long.", + "name": "id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Your application's unique identifier for this user.", + "name": "external_id", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Membership updated successfully. Returns the updated user object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/usersUpdateMembershipResponse" + } + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Membership fields to update. Only specified fields will be modified.", + "$ref": "#/components/schemas/v1usersUpdateMembership", + "examples": [ + { + "role": "admin" + } + ] + } + } + }, + "required": true + } + } + }, + "/api/v1/organizations": { + "get": { + "description": "Retrieve a paginated list of organizations within your environment. The response includes a `page_token` that can be used to access subsequent pages of results.", + "tags": [ + "Organizations" + ], + "summary": "List organizations", + "operationId": "OrganizationService_ListOrganization", + "parameters": [ + { + "schema": { + "type": "integer", + "format": "int64" + }, + "description": "Maximum number of organizations to return per page. Must be between 10 and 100", + "name": "page_size", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Pagination token from the previous response. Use to retrieve the next page of organizations", + "name": "page_token", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Your application's unique identifier for this organization, used to link Scalekit with your system", + "name": "external_id", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved the list of organizations", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/organizationsListOrganizationsResponse" + } + } + } + }, + "400": { + "description": "Invalid page token", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const organizations = await scalekit.organization.listOrganization({\n\tpageSize: 10,\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "options = ListOrganizationOptions()\noptions.page_size = 10\n\norganizations = scalekit_client.organization.list_organizations(\n options=options\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "organizations, err := scalekitClient.Organization.ListOrganizations(\n ctx,\n &scalekit.ListOrganizationOptions{\n PageSize: 10,\n }\n)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ListOrganizationsResponse organizations = scalekitClient.organizations().listOrganizations(10, \"\");" + } + ] + }, + "post": { + "description": "Creates a new organization in your environment. Use this endpoint to add a new tenant that can be configured with various settings and metadata", + "tags": [ + "Organizations" + ], + "summary": "Create an organization", + "operationId": "OrganizationService_CreateOrganization", + "responses": { + "201": { + "description": "Returns the newly created organization with its unique identifier and settings", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/organizationsCreateOrganizationResponse" + } + } + } + } + }, + "x-badges": [ + { + "name": "" + } + ], + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const organization = await scalekit.organization.createOrganization(name, {\n\n\texternalId: \"externalId\",\n\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "options = CreateOrganizationOptions()\noptions.external_id = \"externalId\"\norganization = scalekit_client.organization.create_organization(\n name,\n options=options\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "organization, err := ScalekitClient.Organization.CreateOrganization(\n ctx,\n name,\n scalekit.CreateOrganizationOptions{\n ExternalID: \"externalId\",\n },\n)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "CreateOrganization createOrganization = CreateOrganization.newBuilder()\n .setDisplayName(\"Test Org\")\n .build();\n\nOrganization createdOrganization = scalekitClient.organizations().create(createOrganization);" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Required parameters for creating a new organization", + "$ref": "#/components/schemas/v1organizationsCreateOrganization" + } + } + }, + "description": "Organization details", + "required": true + } + } + }, + "/api/v1/organizations/{id}": { + "get": { + "description": "Retrieves organization details by Scalekit ID, including name, region, metadata, and settings", + "tags": [ + "Organizations" + ], + "summary": "Get organization details", + "operationId": "OrganizationService_GetOrganization", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique scalekit-generated identifier that uniquely references an organization", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Returns the complete organization object with ID, display name, settings, and metadata", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/organizationsGetOrganizationResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const scalekit = new ScalekitClient(\n ,\n ,\n \n);\n\nconst organization = await scalekit.organization.getOrganization(organization_id);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "scalekit_client = ScalekitClient(\n ,\n ,\n \n)\n\norganization = scalekit_client.organization.get_organization(\n organization_id\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "scalekitClient := scalekit.NewScalekitClient(\n ,\n ,\n \n)\n\norganization, err := scalekitClient.Organization.GetOrganization(\n ctx,\n organizationId\n)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ScalekitClient scalekitClient = new ScalekitClient(\n \"\",\n \"\",\n \"\"\n);\n\nOrganization organization = scalekitClient.organizations().getById(organizationId);" + } + ] + }, + "delete": { + "description": "Remove an existing organization from the environment using its unique identifier", + "tags": [ + "Organizations" + ], + "summary": "Delete an organization", + "operationId": "OrganizationService_DeleteOrganization", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique scalekit-generated identifier that uniquely references an organization", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Organization successfully deleted and no longer accessible", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.organization.deleteOrganization(organizationId);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "scalekit_client.organization.delete_organization(organization_id)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "err := scalekitClient.Organization.DeleteOrganization(\n ctx,\n organizationId\n)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ScalekitClient scalekitClient = new ScalekitClient(\n \"\",\n \"\",\n \"\"\n);\n\nscalekitClient.organizations().deleteById(organizationId);" + } + ] + }, + "patch": { + "description": "Updates an organization's display name, external ID, or metadata. Requires a valid organization identifier. Region code cannot be modified through this endpoint.", + "tags": [ + "Organizations" + ], + "summary": "Update organization details", + "operationId": "OrganizationService_UpdateOrganization", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization to be updated", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Returns the updated organization with all current details reflected in the response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/organizationsUpdateOrganizationResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const organization = await scalekit.organization.updateOrganization(organization_id, {\n displayName: 'displayName',\n externalId: 'externalId',\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "organization = scalekit_client.organization.update_organization(organization_id, {\n display_name: \"display_name\",\n external_id: \"external_id\"\n})" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "organization, err := scalekitClient.Organization.UpdateOrganization(\n ctx,\n organizationId,\n &scalekit.UpdateOrganization{\n DisplayName: \"displayName\",\n ExternalId: \"externalId\",\n },\n)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "UpdateOrganization updateOrganization = UpdateOrganization.newBuilder()\n .setDisplayName(\"Updated Organization Name\")\n .build();\n\nOrganization updatedOrganizationById = scalekitClient.organizations().updateById(organizationId, updateOrganization);" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Organization Parameters to be updated", + "$ref": "#/components/schemas/v1organizationsUpdateOrganization" + } + } + }, + "required": true + } + } + }, + "/api/v1/organizations/{id}/portal_links": { + "put": { + "description": "Creates a single use Admin Portal URL valid for 1 minute. Once the generated admin portal URL is accessed or rendered, a temporary session of 6 hours is created to allow the admin to update SSO/SCIM configuration.", + "tags": [ + "Organizations" + ], + "summary": "Generate admin portal link", + "operationId": "OrganizationService_GeneratePortalLink", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Organization ID", + "name": "id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "array", + "items": { + "enum": [ + "dir_sync", + "sso" + ], + "type": "string" + } + }, + "style": "form", + "explode": true, + "description": "Features to enable in the admin portal link. To enable features, append them as URL parameters:\n\n- Single Sign-On: ?features=sso\n- Directory Sync: ?features=dir_sync\n- Both features: ?features=sso&features=dir_sync\n\nExample URL: https://scalekit.com/portal/lnk_123?features=sso\n\n - dir_sync: Enables directory synchronization configuration in the portal\n - sso: Enables Single Sign-On (SSO) configuration in the portal", + "name": "features", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Admin Portal link generated successfully. Returns the portal URL and expiration timestamp.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/organizationsGeneratePortalLinkResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const link = await scalekit.organization.generatePortalLink(organizationId);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "link = scalekit_client.organization.generate_portal_link(\n organization_id\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "link, err := scalekitClient.Organization.GeneratePortalLink(\n ctx,\n organizationId\n)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "Link portalLink = client\n .organizations()\n .generatePortalLink(organizationId, Arrays.asList(Feature.sso, Feature.dir_sync));" + } + ] + } + }, + "/api/v1/organizations/{id}/settings": { + "patch": { + "description": "Updates configuration settings for an organization. Supports modifying SSO configuration, directory synchronization settings, and session parameters. Requires organization ID and the specific settings to update.", + "tags": [ + "Organizations" + ], + "summary": "Toggle organization settings", + "operationId": "OrganizationService_UpdateOrganizationSettings", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization to update settings. Must begin with 'org_' prefix", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Returns the complete organization object with updated settings applied. Contains all organization details including ID, display name, and the modified settings.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/organizationsGetOrganizationResponse" + } + } + } + }, + "400": { + "description": "Invalid request - occurs when the settings payload contains invalid values or unsupported configuration", + "content": { + "application/json": { + "schema": {} + } + } + }, + "404": { + "description": "Organization not found - the specified organization ID doesn't exist", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const settings = {\n features: [\n {\n name: 'sso',\n enabled: true,\n },\n {\n name: 'dir_sync',\n enabled: true,\n },\n ],\n};\n\nawait scalekit.organization.updateOrganizationSettings('', settings);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "settings = [\n {\n \"name\": \"sso\",\n \"enabled\": True\n },\n {\n \"name\": \"dir_sync\",\n \"enabled\": True\n }\n ]\n\nscalekit_client.organization.update_organization_settings(\n organization_id='', settings=settings\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "settings := OrganizationSettings{\n\n\t\tFeatures: []Feature{\n\n\t\t\t{\n\n\t\t\t\tName: \"sso\",\n\n\t\t\t\tEnabled: true,\n\n\t\t\t},\n\n\t\t\t{\n\n\t\t\t\tName: \"dir_sync\",\n\n\t\t\t\tEnabled: true,\n\n\t\t\t},\n\n\t\t},\n\n\t}\n\n\norganization,err := scalekitClient.Organization().UpdateOrganizationSettings(ctx, organizationId, settings)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "OrganizationSettingsFeature featureSSO = OrganizationSettingsFeature.newBuilder()\n .setName(\"sso\")\n .setEnabled(true)\n .build();\n\nOrganizationSettingsFeature featureDirectorySync = OrganizationSettingsFeature.newBuilder()\n .setName(\"dir_sync\")\n .setEnabled(true)\n .build();\n\nupdatedOrganization = scalekitClient.organizations()\n .updateOrganizationSettings(organization.getId(), List.of(featureSSO,\nfeatureDirectorySync));" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Settings configuration to apply to the organization. Contains feature toggles for SSO, directory synchronization, and other organization capabilities", + "$ref": "#/components/schemas/organizationsOrganizationSettings", + "examples": [ + { + "features": [ + { + "enabled": true, + "name": "sso" + }, + { + "enabled": false, + "name": "directory_sync" + } + ] + } + ] + } + } + }, + "required": true + } + } + }, + "/api/v1/organizations/{org_id}/roles": { + "get": { + "description": "Retrieves all environment roles and organization specific roles. Use this endpoint to view all role definitions, including custom roles and their configurations. You can optionally include permission details for each role to understand their capabilities. This is useful for role management, auditing organization access controls, or understanding the available access levels within the organization.", + "tags": [ + "Roles" + ], + "summary": "List organization roles", + "operationId": "RolesService_ListOrganizationRoles", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization", + "name": "org_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Include additional data in the response. Valid values: 'permissions' (direct permissions only), 'permissions:all' (includes inherited permissions)", + "name": "include", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved list of organization roles. Returns all roles with their metadata and optionally their permissions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesListOrganizationRolesResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.role.listOrganizationRoles(\"org_123\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "res = scalekit_client.roles.list_organization_roles(org_id=\"org_123\")" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Role().ListOrganizationRoles(ctx, \"org_123\")\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ListOrganizationRolesResponse res = scalekitClient.roles().listOrganizationRoles(\"org_123\");" + } + ] + }, + "post": { + "description": "Creates a new role within the specified organization with basic configuration including name, display name, description, and permissions. Use this endpoint to define custom roles that can be assigned to users within the organization. You can create hierarchical roles by extending existing roles and assign specific permissions to control access levels. The role will be scoped to the organization and can be used for organization-specific access control.", + "tags": [ + "Roles" + ], + "summary": "Create organization role", + "operationId": "RolesService_CreateOrganizationRole", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization", + "name": "org_id", + "in": "path", + "required": true + } + ], + "responses": { + "201": { + "description": "Organization role created successfully. Returns the complete role object with system-generated ID and timestamps.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesCreateOrganizationRoleResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.role.createOrganizationRole(\"org_123\", {\n name: \"org_admin\",\n displayName: \"Org Admin\",\n description: \"Organization-scoped role\",\n extends: \"base_role_name\", // optional\n permissions: [\"perm.read\", \"perm.write\"] // optional\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "from scalekit.v1.roles.roles_pb2 import CreateOrganizationRole\n\nrole = CreateOrganizationRole(\n name=\"org_admin\",\n display_name=\"Org Admin\",\n description=\"Organization-scoped role\",\n extends=\"base_role_name\", # optional\n permissions=[\"perm.read\", \"perm.write\"] # optional\n)\n\nscalekit_client.roles.create_organization_role(\n org_id=\"org_123\",\n role=role\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Role().CreateOrganizationRole(ctx, \"org_123\", &rolesv1.CreateOrganizationRole{\n\n\tName: \"org_admin\",\n\n\tDisplayName: \"Org Admin\",\n\n\tDescription: proto.String(\"Organization-scoped role\"), // optional\n\n\tExtends: proto.String(\"base_role_name\"), // optional\n\n\tPermissions: []string{\"perm.read\", \"perm.write\"}, // optional\n\n})" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "CreateOrganizationRoleResponse res = scalekitClient.roles().createOrganizationRole(\n \"org_123\",\n CreateOrganizationRoleRequest.newBuilder()\n .setOrgId(\"org_123\")\n .setRole(\n CreateOrganizationRole.newBuilder()\n .setName(\"org_admin\")\n .setDisplayName(\"Org Admin\")\n .setDescription(\"Organization-scoped role\")\n .setExtends(\"base_role_name\") // optional\n .addPermissions(\"perm.read\") // optional\n .addPermissions(\"perm.write\") // optional\n .build()\n )\n .build()\n);" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Organization role details", + "$ref": "#/components/schemas/v1rolesCreateOrganizationRole" + } + } + }, + "required": true + } + } + }, + "/api/v1/organizations/{org_id}/roles/{role_name}": { + "get": { + "description": "Retrieves complete information for a specific organization role including metadata, inheritance details, and optionally permissions. Use this endpoint to audit role configuration and understand the role's place in the organization's role hierarchy. You can include permission details to see what capabilities the role provides. This operation is useful for role management, user assignment decisions, or understanding organization access controls.", + "tags": [ + "Roles" + ], + "summary": "Get organization role details", + "operationId": "RolesService_GetOrganizationRole", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization", + "name": "org_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique name of the role", + "name": "role_name", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Include additional data in the response. Valid values: 'permissions' (direct permissions only), 'permissions:all' (includes inherited permissions)", + "name": "include", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved organization role details. Returns the role object including metadata and inheritance details. Permissions are included only when requested via the include parameter.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesGetOrganizationRoleResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.role.getOrganizationRole(\"org_123\", \"org_admin\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "res = scalekit_client.roles.get_organization_role(\n org_id=\"org_123\",\n role_name=\"org_admin\"\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Role().GetOrganizationRole(ctx, \"org_123\", \"org_admin\")\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "GetOrganizationRoleResponse res = scalekitClient.roles().getOrganizationRole(\"org_123\", \"org_admin\");" + } + ] + }, + "put": { + "description": "Modifies an existing organization role's properties including display name, description, permissions, and inheritance settings. Use this endpoint to update role metadata, change permission assignments, or modify role hierarchy within the organization. Only the fields you specify will be updated, leaving other properties unchanged. When updating permissions, the new list replaces all existing permissions for the role.", + "tags": [ + "Roles" + ], + "summary": "Update organization role", + "operationId": "RolesService_UpdateOrganizationRole", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization", + "name": "org_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique name of the role", + "name": "role_name", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Organization role updated successfully. Returns the modified role object with updated timestamps.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesUpdateOrganizationRoleResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.role.updateOrganizationRole(\"org_123\", \"org_admin\", {\n displayName: \"Org Admin (Updated)\",\n description: \"Updated org role description\"\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "from scalekit.v1.roles.roles_pb2 import UpdateRole\n\nscalekit_client.roles.update_organization_role(\n org_id=\"org_123\",\n role_name=\"org_admin\",\n role=UpdateRole(\n display_name=\"Org Admin (Updated)\",\n description=\"Updated org role description\"\n )\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Role().UpdateOrganizationRole(ctx, \"org_123\", \"org_admin\", &rolesv1.UpdateRole{\n DisplayName: \"Org Admin (Updated)\",\n Description: \"Updated org role description\",\n})\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "UpdateOrganizationRoleResponse res = scalekitClient.roles().updateOrganizationRole(\n \"org_123\",\n \"org_admin\",\n UpdateOrganizationRoleRequest.newBuilder()\n .setRole(\n UpdateRole.newBuilder()\n .setDisplayName(\"Org Admin (Updated)\")\n .setDescription(\"Updated org role description\")\n .build()\n )\n .build()\n);" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Organization role details", + "$ref": "#/components/schemas/v1rolesUpdateRole" + } + } + }, + "required": true + } + }, + "delete": { + "description": "Permanently removes a role from the organization and optionally reassigns users who had that role to a different role. Use this endpoint when you need to clean up unused roles or restructure your organization's access control system. If users are assigned to the role being deleted, you can provide a reassign_role_name to move those users to a different role before deletion. This action cannot be undone, so ensure no critical users depend on the role before deletion.", + "tags": [ + "Roles" + ], + "summary": "Delete organization role", + "operationId": "RolesService_DeleteOrganizationRole", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization", + "name": "org_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique name of the role", + "name": "role_name", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Role name to reassign users to when deleting this role", + "name": "reassign_role_name", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Organization role successfully deleted and users reassigned if specified. No content returned.", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "// Basic delete\nawait scalekit.role.deleteOrganizationRole(\"org_123\", \"org_role_admin\");\n\n// With reassignment\nawait scalekit.role.deleteOrganizationRole(\"org_123\", \"org_role_admin\", \"org_role_member\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "# Basic delete\nscalekit_client.roles.delete_organization_role(\n org_id=\"org_123\",\n role_name=\"org_role_admin\"\n)\n\n# With reassignment\nscalekit_client.roles.delete_organization_role(\n org_id=\"org_123\",\n role_name=\"org_role_admin\",\n reassign_role_name=\"org_role_member\"\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "// Basic delete\nerr := scalekitClient.Role().DeleteOrganizationRole(ctx, \"org_123\", \"org_role_admin\")\nif err != nil { /* handle err */ }\n\n// With reassignment\nerr = scalekitClient.Role().DeleteOrganizationRole(ctx, \"org_123\", \"org_role_admin\", \"org_role_member\")" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "// Basic delete\nscalekitClient.roles().deleteOrganizationRole(\"org_123\", \"org_role_admin\");\n\n// With reassignment\nscalekitClient.roles().deleteOrganizationRole(\"org_123\", \"org_role_admin\", \"org_role_member\");" + } + ] + } + }, + "/api/v1/organizations/{org_id}/roles:set_defaults": { + "patch": { + "description": "Updates the default member role for the specified organization. Use this endpoint to configure which role is automatically assigned to new users when they join the organization. The system will validate that the specified role exists and update the organization settings accordingly. This configuration affects all new user invitations and memberships within the organization.", + "tags": [ + "Roles" + ], + "summary": "Set default organization roles", + "operationId": "RolesService_UpdateDefaultOrganizationRoles", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization", + "name": "org_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Default organization roles updated successfully. Returns the updated default member role object with complete role information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesUpdateDefaultOrganizationRolesResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.role.updateDefaultOrganizationRoles(\"org_123\", {\n defaultMemberRole: \"org_member\"\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "from scalekit.v1.roles.roles_pb2 import UpdateDefaultOrganizationRolesRequest\n\nres = scalekit_client.roles.update_default_organization_roles(\n org_id=\"org_123\",\n default_roles=UpdateDefaultOrganizationRolesRequest(\n default_member_role=\"org_member\"\n )\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Role().UpdateDefaultOrganizationRoles(ctx, \"org_123\", \"org_member\")\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "UpdateDefaultOrganizationRolesResponse res = scalekitClient.roles().updateDefaultOrganizationRoles(\n \"org_123\",\n UpdateDefaultOrganizationRolesRequest.newBuilder()\n .setDefaultMemberRole(\"org_member\")\n .build()\n);" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RolesServiceUpdateDefaultOrganizationRolesBody" + } + } + }, + "required": true + } + } + }, + "/api/v1/organizations/{organization_id}/clients": { + "get": { + "description": "Retrieves a paginated list of API clients for a specific organization. Returns client details including metadata, scopes, and secret information (without exposing actual secret values).", + "tags": [ + "API Auth" + ], + "summary": "List organization API clients", + "operationId": "ClientService_ListOrganizationClients", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization whose clients to list. Must start with 'org_' prefix.", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "integer", + "format": "int64" + }, + "description": "Maximum number of clients to return per page\n\nMaximum number of API clients to return per page. Must be between 10 and 100", + "name": "page_size", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Pagination token from the previous response\n\nPagination token from the previous response. Use to retrieve the next page of organization clients", + "name": "page_token", + "in": "query" + } + ], + "responses": { + "200": { + "description": "List of organization API clients returned successfully. Each client includes its configuration details and metadata.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/clientsListOrganizationClientsResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Python SDK", + "lang": "python", + "source": "# List clients for a specific organization\norg_id = 'SCALEKIT_ORGANIZATION_ID'\n\n# Retrieve all clients with default pagination\nresponse = scalekit_client.m2m_client.list_organization_clients(\n organization_id=org_id,\n page_size=30\n)\n\n# Access the clients list\nclients = response.clients\nfor client in clients:\n print(f\"Client ID: {scalekit_client.id}, Name: {scalekit_client.name}\")" + } + ] + }, + "post": { + "description": "Creates a new API client for an organization. Returns the client details and a plain secret (available only once).", + "tags": [ + "API Auth" + ], + "summary": "Create organization API client", + "operationId": "ClientService_CreateOrganizationClient", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization", + "name": "organization_id", + "in": "path", + "required": true + } + ], + "responses": { + "201": { + "description": "API client created successfully. Returns the client ID and plain secret (only available at creation time). The client can be configured with scopes, audience values, and custom claims for fine-grained access control.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/clientsCreateOrganizationClientResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Python SDK", + "lang": "python", + "source": "from scalekit.v1.clients.clients_pb2 import OrganizationClient\n\nm2m_client = OrganizationClient(\n name=\"GitHub Actions Deployment Service\",\n description=\"Service account for GitHub Actions to deploy applications\nto production\",\n custom_claims=[\n {\"key\": \"github_repository\", \"value\": \"acmecorp/inventory-service\"},\n {\"key\": \"environment\", \"value\": \"production_us\"}\n ],\n scopes=[\"deploy:applications\", \"read:deployments\"],\n audience=[\"deployment-api.acmecorp.com\"],\n expiry=3600\n)\n\nresponse = scalekit_client.m2m_client.create_organization_client(\n organization_id=\"SCALEKIT_ORGANIZATION_ID\",\n m2m_client=m2m_client\n)" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Details of the client to be created", + "$ref": "#/components/schemas/clientsOrganizationClient" + } + } + }, + "required": true + } + } + }, + "/api/v1/organizations/{organization_id}/clients/{client_id}": { + "get": { + "description": "Retrieves details of a specific API client in an organization.", + "tags": [ + "API Auth" + ], + "summary": "Get organization API client", + "operationId": "ClientService_GetOrganizationClient", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the API client", + "name": "client_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Returns the complete API client configuration, including all current settings and a list of active secrets. Note that secret values are not included in the response for security reasons.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/clientsGetOrganizationClientResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Python SDK", + "lang": "python", + "source": "# Get client ID from environment variables\norg_id = 'SCALEKIT_ORGANIZATION_ID'\nclient_id = os.environ['M2M_CLIENT_ID']\n\n# Fetch client details for the specified organization\nresponse = scalekit_client.m2m_client.get_organization_client(\n organization_id=org_id,\n client_id=client_id\n)" + } + ] + }, + "delete": { + "description": "Permanently deletes an API client from an organization. This operation cannot be undone and will revoke all access for the client. All associated secrets will also be invalidated. Use this endpoint to remove unused or compromised clients.", + "tags": [ + "API Auth" + ], + "summary": "Delete organization API client", + "operationId": "ClientService_DeleteOrganizationClient", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization that owns the client. Must start with 'org_' prefix.", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the API client to permanently delete. Must start with 'm2morg_' prefix.", + "name": "client_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Organization API client successfully deleted and no longer accessible", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-codeSamples": [ + { + "label": "Python SDK", + "lang": "python", + "source": "# Get client ID from environment variables\norg_id = ''\nclient_id = os.environ['M2M_CLIENT_ID']\n\n# Delete the specified client from the organization\nresponse = scalekit_client.m2m_client.delete_organization_client(\n organization_id=org_id,\n client_id=client_id\n)" + } + ] + }, + "patch": { + "description": "Updates an existing organization API client. Only specified fields are modified.", + "tags": [ + "API Auth" + ], + "summary": "Update organization API client", + "operationId": "ClientService_UpdateOrganizationClient", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the client", + "name": "client_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Returns the updated organization API client with all current details reflected in the response, including modified scopes, audience values, and custom claims.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/clientsUpdateOrganizationClientResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Python SDK", + "lang": "python", + "source": "from scalekit.v1.clients.clients_pb2 import OrganizationClient\n\norg_id = ''\nclient_id = os.environ['M2M_CLIENT_ID']\n\nupdate_m2m_client = OrganizationClient(\n description=\"Service account for GitHub Actions to deploy applications\nto production_eu\",\n custom_claims=[\n {\"key\": \"github_repository\", \"value\": \"acmecorp/inventory\"},\n {\"key\": \"environment\", \"value\": \"production_eu\"}\n ]\n)\n\nresponse = scalekit_client.m2m_client.update_organization_client(\n organization_id=org_id,\n client_id=client_id,\n m2m_client=update_m2m_client\n)" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Updated details for the client", + "$ref": "#/components/schemas/clientsOrganizationClient" + } + } + }, + "required": true + } + } + }, + "/api/v1/organizations/{organization_id}/clients/{client_id}/secrets": { + "post": { + "description": "Creates a new secret for an organization API client. Returns the plain secret (available only once).", + "tags": [ + "API Auth" + ], + "summary": "Create organization API client secret", + "operationId": "ClientService_CreateOrganizationClientSecret", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the API client", + "name": "client_id", + "in": "path", + "required": true + } + ], + "responses": { + "201": { + "description": "Client secret created successfully. Returns the new secret ID and the plain secret value (only available at creation time). The secret can be used immediately for authentication.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/clientsCreateOrganizationClientSecretResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Python SDK", + "lang": "python", + "source": "# Get client ID from environment variables\norg_id = 'SCALEKIT_ORGANIZATION_ID'\nclient_id = os.environ['M2M_CLIENT_ID']\n\n# Add a new secret to the specified client\nresponse = scalekit_client.m2m_client.add_organization_client_secret(\n organization_id=org_id,\n client_id=client_id\n)\n\n# Extract the secret ID from the response\nsecret_id = response[0].secret.id" + } + ] + } + }, + "/api/v1/organizations/{organization_id}/clients/{client_id}/secrets/{secret_id}": { + "delete": { + "description": "Permanently deletes a secret from an organization API client. This operation cannot be undone.", + "tags": [ + "API Auth" + ], + "summary": "Delete organization API client secret", + "operationId": "ClientService_DeleteOrganizationClientSecret", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the API client", + "name": "client_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the client secret", + "name": "secret_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Client secret successfully deleted and no longer accessible", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-codeSamples": [ + { + "label": "Python SDK", + "lang": "python", + "source": "# Get client and secret IDs from environment variables\norg_id = ''\nclient_id = os.environ['M2M_CLIENT_ID']\nsecret_id = os.environ['M2M_SECRET_ID']\n\n# Remove the specified secret from the client\nresponse = scalekit_client.m2m_client.remove_organization_client_secret(\n organization_id=org_id,\n client_id=client_id,\n secret_id=secret_id\n)" + } + ] + } + }, + "/api/v1/organizations/{organization_id}/connections/{id}": { + "get": { + "description": "Retrieves the complete configuration and status details for a specific connection by its ID within an organization. Returns all connection properties including provider settings, protocols, and current status.", + "tags": [ + "Connections" + ], + "summary": "Get connection details", + "operationId": "ConnectionService_GetConnection", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Organization identifier (required). Specifies which organization owns the connection you want to retrieve.", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Connection identifier (required). Specifies which specific connection to retrieve from the organization.", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully retrieved connection details for the specified organization", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connectionsGetConnectionResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const connection = await scalekit.connection.getConnection(\n organizationId,\n connectionId\n);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "connection = scalekit_client.connection.get_connection(\n organization_id,\n connection_id,\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "connection, err := scalekitClient.Connection.GetConnection(\n ctx,\n organizationId,\n connectionId,\n)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "Connection connection = scalekitClient.connections().getConnectionById(connectionId, organizationId);" + } + ] + }, + "delete": { + "description": "Deletes an SSO connection from the specified organization by connection ID. Use this endpoint when an identity provider integration is no longer needed for the organization. Returns an empty response after the SSO connection is deleted successfully.", + "tags": [ + "Connections" + ], + "summary": "Delete SSO connection", + "operationId": "ConnectionService_DeleteConnection", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Organization ID for the Connection.", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Connection ID. Unique ID for the connection", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "SSO connection deleted successfully", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.connection.deleteConnection(organizationId, connectionId);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "scalekit_client.connection.delete_connection(\n organization_id,\n connection_id\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "err := scalekitClient.Connection.DeleteConnection(\n ctx,\n organizationId,\n connectionId,\n)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "scalekitClient.connections().deleteConnection(connectionId, organizationId);" + } + ] + } + }, + "/api/v1/organizations/{organization_id}/connections/{id}:disable": { + "patch": { + "description": "Deactivate an existing connection for the specified organization. When disabled, users cannot authenticate using this connection. This endpoint changes the connection state from enabled to disabled without modifying other configuration settings", + "tags": [ + "Connections" + ], + "summary": "Disable SSO connection", + "operationId": "ConnectionService_DisableConnection", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization associated with the connection", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique identifier for the connection to be toggled", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Connection disabled successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connectionsToggleConnectionResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.connection.disableConnection(organizationId, connectionId);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "scalekit_client.connection.disable_connection(\n organization_id,\n connection_id\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "err := scalekitClient.Connection.DisableConnection(\n ctx,\n organizationId,\n connectionId,\n)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ToggleConnectionResponse response = scalekitClient.connections().disableConnection(connectionId, organizationId);" + } + ] + } + }, + "/api/v1/organizations/{organization_id}/connections/{id}:enable": { + "patch": { + "description": "Activate an existing connection for the specified organization. When enabled, users can authenticate using this connection. This endpoint changes the connection state from disabled to enabled without modifying other configuration settings", + "tags": [ + "Connections" + ], + "summary": "Enable SSO connection", + "operationId": "ConnectionService_EnableConnection", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization associated with the connection", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique identifier for the connection to be toggled", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Connection enabled successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/connectionsToggleConnectionResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.connection.enableConnection(organizationId, connectionId);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "scalekit_client.connection.enable_connection(\n organization_id,\n connection_id,\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "err := scalekitClient.Connection.EnableConnection(\n ctx,\n organizationId,\n connectionId,\n)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ToggleConnectionResponse response = scalekitClient.connections().enableConnection(connectionId, organizationId);" + } + ] + } + }, + "/api/v1/organizations/{organization_id}/directories": { + "get": { + "tags": [ + "Directory" + ], + "summary": "List organization directories", + "operationId": "DirectoryService_ListDirectories", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization", + "name": "organization_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully retrieved the list of directories for the organization", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/directoriesListDirectoriesResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.directory.listDirectories('');" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "directories_list = scalekit_client.directory.list_directories(\n\torganization_id=''\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "directories,err := scalekitClient.Directory().ListDirectories(ctx, organizationId)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ListDirectoriesResponse response = scalekitClient.directories().listDirectories(organizationId);" + } + ] + } + }, + "/api/v1/organizations/{organization_id}/directories/{directory_id}/groups": { + "get": { + "description": "Retrieves all groups from a specified directory. Use this endpoint to view group structures from your connected identity provider.", + "tags": [ + "Directory" + ], + "summary": "List directory groups", + "operationId": "DirectoryService_ListDirectoryGroups", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the directory", + "name": "directory_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "integer", + "format": "int64" + }, + "description": "Number of groups to return per page. Maximum value is 30. If not specified, defaults to 10", + "name": "page_size", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Token for pagination. Use the value returned in the 'next_page_token' field of the previous response", + "name": "page_token", + "in": "query" + }, + { + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Filter groups updated after this timestamp. Use ISO 8601 format", + "name": "updated_after", + "in": "query" + }, + { + "schema": { + "type": "boolean" + }, + "description": "If true, includes full group details. If false or not specified, returns basic information only", + "name": "include_detail", + "in": "query" + }, + { + "schema": { + "type": "boolean" + }, + "description": "If true, returns group and its details from external provider (default: false)", + "name": "include_external_groups", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved the list of groups from the specified directory", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/directoriesListDirectoryGroupsResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const { groups } = await scalekit.directory.listDirectoryGroups(\n '',\n ''\n);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "directory_groups = scalekit_client.directory.list_directory_groups(\n directory_id='', organization_id=''\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "options := &ListDirectoryGroupsOptions{\n\n\t\tPageSize: 10,\n\n\t\tPageToken:\"\",\n\n\t}\n\n\ndirectoryGroups, err := scalekitClient.Directory().ListDirectoryGroups(ctx, organizationId, directoryId, options)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "var options = ListDirectoryResourceOptions.builder()\n .pageSize(10)\n .pageToken(\"\")\n .includeDetail(true)\n .build();\n\nListDirectoryGroupsResponse groupsResponse = scalekitClient\n .directories()\n .listDirectoryGroups(directory.getId(), organizationId, options);" + } + ] + } + }, + "/api/v1/organizations/{organization_id}/directories/{directory_id}/users": { + "get": { + "description": "Retrieves a list of all users within a specified directory for an organization. This endpoint allows you to view user accounts associated with your connected Directory Providers.", + "tags": [ + "Directory" + ], + "summary": "List directory users", + "operationId": "DirectoryService_ListDirectoryUsers", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the directory within the organization", + "name": "directory_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "integer", + "format": "int64" + }, + "description": "Number of users to return per page. Maximum value is 30. If not specified, defaults to 10", + "name": "page_size", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Token for pagination. Use the value returned in the 'next_page_token' field of the previous response to retrieve the next page of results", + "name": "page_token", + "in": "query" + }, + { + "schema": { + "type": "boolean" + }, + "description": "If set to true, the response will include the full user payload with all available details. If false or not specified, only essential user information will be returned", + "name": "include_detail", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Filter users by their membership in a specific directory group", + "name": "directory_group_id", + "in": "query" + }, + { + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Filter users that were updated after the specified timestamp. Use ISO 8601 format", + "name": "updated_after", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved the list of users from the specified directory", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/directoriesListDirectoryUsersResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const { users } = await scalekit.directory.listDirectoryUsers(\n '',\n ''\n);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "directory_users = scalekit_client.directory.list_directory_users(\n directory_id='', organization_id=''\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "options := &ListDirectoryUsersOptions{\n\n\t\tPageSize: 10,\n\n\t\tPageToken: \"\",\n\n\t}\n\ndirectoryUsers,err := scalekitClient.Directory().ListDirectoryUsers(ctx, organizationId, directoryId, options)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "var options = ListDirectoryResourceOptions.builder()\n .pageSize(10)\n .pageToken(\"\")\n .includeDetail(true)\n .build();\n\nListDirectoryUsersResponse usersResponse = scalekitClient\n .directories()\n .listDirectoryUsers(directory.getId(), organizationId, options);" + } + ] + } + }, + "/api/v1/organizations/{organization_id}/directories/{id}": { + "get": { + "description": "Retrieves detailed information about a specific directory within an organization", + "tags": [ + "Directory" + ], + "summary": "Get directory details", + "operationId": "DirectoryService_GetDirectory", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the directory", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully retrieved directory details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/directoriesGetDirectoryResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const { directory } = await scalekit.directory.getDirectory(\n organizationId,\n directoryId\n);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "directory = scalekit_client.directory.get_directory(\n directory_id='', organization_id=''\n)\nprint(f'Directory details: {directory}')" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "directory, err := scalekitClient.Directory().GetDirectory(ctx, organizationId, directoryId)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "Directory directory = scalekitClient.directories().getDirectory(directoryId, organizationId);" + } + ] + } + }, + "/api/v1/organizations/{organization_id}/directories/{id}:disable": { + "patch": { + "description": "Stops synchronization of users and groups from a specified directory within an organization. This operation prevents further updates from the connected Directory provider", + "tags": [ + "Directory" + ], + "summary": "Disable a directory", + "operationId": "DirectoryService_DisableDirectory", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "A unique identifier for the organization. The value must begin with 'org_' and be between 1 and 32 characters long", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "A unique identifier for a directory within the organization. The value must begin with 'dir_' and be between 1 and 32 characters long", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully disabled the directory", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/directoriesToggleDirectoryResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.directory.disableDirectory(\n '',\n ''\n);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "directory_response = scalekit_client.directory.disable_directory(\n directory_id='', organization_id=''\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "disable,err := scalekitClient.Directory().DisableDirectory(ctx, organizationId, directoryId)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ToggleDirectoryResponse disableResponse = scalekitClient\n .directories()\n .disableDirectory(directoryId, organizationId);" + } + ] + } + }, + "/api/v1/organizations/{organization_id}/directories/{id}:enable": { + "patch": { + "description": "Activates a directory within an organization, allowing it to synchronize users and groups with the connected Directory provider", + "tags": [ + "Directory" + ], + "summary": "Enable a directory", + "operationId": "DirectoryService_EnableDirectory", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "A unique identifier for the organization. The value must begin with 'org_' and be between 1 and 32 characters long", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "A unique identifier for a directory within the organization. The value must begin with 'dir_' and be between 1 and 32 characters long", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/directoriesToggleDirectoryResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.directory.enableDirectory('', '');" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "directory_response = scalekit_client.directory.enable_directory(\n directory_id='', organization_id=''\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "enable,err := scalekitClient.Directory().EnableDirectory(ctx, organizationId, directoryId)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ToggleDirectoryResponse enableResponse = client\n .directories()\n .enableDirectory(directoryId, organizationId);" + } + ] + } + }, + "/api/v1/organizations/{organization_id}/domains": { + "get": { + "description": "Retrieves a paginated list of all domains configured for the specified organization.\n\nDomain types:\n- ALLOWED_EMAIL_DOMAIN: Trusted domains used to suggest the organization in the organization switcher during sign-in/sign-up (auth-method agnostic).\n- ORGANIZATION_DOMAIN: SSO discovery domains used to route users to the correct SSO provider and enforce SSO.\n\n", + "tags": [ + "Domains" + ], + "summary": "List Domains", + "operationId": "DomainService_ListDomains", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Scalekit-generated unique identifier for the organization. Use either this or external_id to identify the organization.", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Optional comma-separated list of additional fields to include in the response (e.g., 'verification_details').", + "name": "include", + "in": "query" + }, + { + "schema": { + "type": "integer", + "format": "int32" + }, + "description": "Maximum number of domains to return per page. Default is 30, maximum is 100.", + "name": "page_size", + "in": "query" + }, + { + "schema": { + "type": "integer", + "format": "int32" + }, + "description": "Page number to retrieve (0-based). Use 0 for the first page.", + "name": "page_number", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "ALLOWED_EMAIL_DOMAIN", + "ORGANIZATION_DOMAIN" + ] + }, + "description": "The domain type.\n- ALLOWED_EMAIL_DOMAIN: trusted domain used to suggest the organization in the organization switcher during sign-in/sign-up.\n- ORGANIZATION_DOMAIN: SSO discovery domain used to route users to the correct SSO provider and enforce SSO.\n", + "name": "domain_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved the list of domains.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/domainsListDomainResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "// List all domains in an organization\nconst response = await scalekit.domain.listDomains(organizationId, {\n\tdomainType: \"ORGANIZATION_DOMAIN\"\n});\n\n// Domain object contains:\n// - id: Domain identifier\n// - domain: Domain name\n// - organizationId: Owning organization\n// - domainType: Configuration type" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "# List all domains in an organization\nresponse = scalekit_client.domain.list_domains(\n organization_id=\"org_123\",\n domain_type=\"ORGANIZATION_DOMAIN\"\n )\n# - organization_id: Owning organization\n# - domain_type: domain type" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "domains, err := scalekitClient.Domain().ListDomains(ctx, \"org_id\", &scalekit.ListDomainOptions{\nDomainType: \"ORGANIZATION_DOMAIN\",\n})" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "List domains = scalekitClient.domains().listDomainsByOrganizationId(\"org_id\", \"ORGANIZATION_DOMAIN\");" + } + ] + }, + "post": { + "description": "Creates and associates a domain with an organization.\n\nUse one of the following domain types:\n- ALLOWED_EMAIL_DOMAIN: Adds a trusted email domain for organization suggestions in the organization switcher during sign-in/sign-up (auth-method agnostic).\n- ORGANIZATION_DOMAIN: Enables SSO domain discovery. If a user signs in with a matching email domain, Scalekit redirects them to the organization’s SSO provider and enforces SSO.\n\nThe domain must be a valid business domain that you control. Public/disposable domains (e.g., gmail.com) are blocked for security.\n\n", + "tags": [ + "Domains" + ], + "summary": "Create Domain", + "operationId": "DomainService_CreateDomain", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Scalekit-generated unique identifier for the organization. Use either this or external_id to identify the organization.", + "name": "organization_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully created the domain.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/domainsCreateDomainResponse" + } + } + } + }, + "400": { + "description": "Invalid request — common causes invalid domain format, public or disposable domain, or domain already exists.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/errdetailsErrorInfo" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "// Add a new domain to an organization\nconst response = await scalekit.createDomain(\"org-123\", \"example.com\", {\n\n\t// Domain type: controls user authentication and email validation\n\n\tdomainType: \"ORGANIZATION_DOMAIN\",\n\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "# Add a new domain to an organization\nresponse = scalekit_client.domain.create_domain(organization_id=\"org-123\",\n\n\t\t\tdomain_name=\"example.com\",\n \t\t\tdomain_type=\"ORGANIZATION_DOMAIN\")" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "domain, err := scalekitClient.Domain().CreateDomain(ctx, \"org_id\", \"example.com\", &scalekit.CreateDomainOptions{\n\n\t\tDomainType: \"ORGANIZATION_DOMAIN\",\n\n\t})" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "CreateDomainRequest request = CreateDomainRequest.newBuilder()\n\t.setOrganizationId(organization.getId())\n\t.setDomain(CreateDomain.newBuilder()\n\t\t.setDomain(\"example.com\")\n\t\t.setDomainType(\"ORGANIZATION_DOMAIN\")\n\t\t.build())\n\t.build();\n\t\nDomain domain = scalekitClient.domains().createDomain(request);" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Domain configuration including the domain name and type.", + "$ref": "#/components/schemas/v1domainsCreateDomain" + } + } + }, + "required": true + } + } + }, + "/api/v1/organizations/{organization_id}/domains/{id}": { + "get": { + "description": "Retrieves complete details for a domain including domain type, timestamps, and configuration information.\n\n", + "tags": [ + "Domains" + ], + "summary": "Get Domain", + "operationId": "DomainService_GetDomain", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Scalekit-generated unique identifier for the organization. Use either this or external_id to identify the organization.", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Scalekit-generated unique identifier of the domain to retrieve.", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully retrieved the domain details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/domainsGetDomainResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "// Fetch details of a specific domain\nconst response = await scalekit.domain.getDomain(organizationId, domainId);\n\n// Domain object properties:\n// - id: Domain identifier\n// - domain: Domain name\n// - organizationId: Owning organization\n// - domainType: Domain configuration type" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "# Fetch details of a specific domain\nresponse = scalekit_client.domain.get_domain(organization_id=\"org_123\", domain_id=\"dom_123\")" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "domain, err := scalekitClient.Domain().GetDomain(ctx, \"dom_123\", \"org_123\")" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "Domain domain = scalekitClient.domains().getDomainById(\"org_123\", \"dom_123\");" + } + ] + }, + "delete": { + "description": "Permanently removes a domain record from an organization.\n\n- Deleting an ORGANIZATION_DOMAIN disables SSO routing/enforcement for that domain.\n- Deleting an ALLOWED_EMAIL_DOMAIN stops organization suggestions for users with that email domain.\n\n", + "tags": [ + "Domains" + ], + "summary": "Delete Domain", + "operationId": "DomainService_DeleteDomain", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Scalekit-generated unique identifier for the organization. Use either this or external_id to identify the organization.", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Scalekit-generated unique identifier of the domain to be permanently deleted.", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Domain successfully deleted.", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "// Remove a domain from an organization\n// Caution: Deletion is permanent and may affect user access\nconst response = await scalekit.domain.deleteDomain(organizationId, domainId);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "# Remove a domain from an organization\n# Caution: Deletion is permanent and may affect user access\nresponse = scalekit_client.domain.delete_domain(\n organization_id=\"org_123\",\n domain_id=\"dom_123\"\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "err = scalekitClient.Domain().DeleteDomain(ctx, \"dom_123\", \"org_123\")" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "scalekitClient.domains().deleteDomain(organization.getId(), domain.getId());" + } + ] + } + }, + "/api/v1/organizations/{organization_id}/settings/usermanagement": { + "patch": { + "description": "Upsert user management settings for an organization", + "tags": [ + "Organizations" + ], + "summary": "Upsert organization user setting", + "operationId": "OrganizationService_UpsertUserManagementSettings", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "ID of the organization.", + "name": "organization_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Returns the updated organization setting.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/organizationsUpsertUserManagementSettingsResponse" + } + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationServiceUpsertUserManagementSettingsBody" + } + } + }, + "required": true + } + } + }, + "/api/v1/organizations/{organization_id}/users": { + "get": { + "description": "Retrieves a paginated list of all users who are members of the specified organization. Use this endpoint to view all users with access to a particular organization, including their roles, metadata, and membership details. Supports pagination for large user lists.", + "tags": [ + "Users" + ], + "summary": "List organization users", + "operationId": "UserService_ListOrganizationUsers", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization for which to list users. Must start with 'org_' and be 1-32 characters long.", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "integer", + "format": "int64" + }, + "description": "Maximum number of users to return in a single response. Valid range: 1-100. Server may return fewer users than specified.", + "name": "page_size", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Pagination token from a previous ListUserResponse. Used to retrieve the next page of results. Leave empty for the first request.", + "name": "page_token", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved the list of users in the organization", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/usersListOrganizationUsersResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const response = await scalekit.user.\n listOrganizationUsers(\"org_123\", {\n\tpageSize: 50,\n});\nconsole.log(response.users);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "resp, _ = scalekit_client.users.list_users(organization_id=\"org_123\", page_size=50)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "list, \n err := scalekitClient.User().ListOrganizationUsers(ctx, \"org_123\", &scalekit.ListUsersOptions{PageSize:\n50}) if err != nil { /* handle error */ }\nfmt.Println(list.Users)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ListOrganizationUsersRequest listReq = ListOrganiz\n ationUsersRequest.newBuilder()\n .setPageSize(50)\n .build();\nListOrganizationUsersResponse list = users.\n listOrganizationUsers(\"org_123\", listReq);" + } + ] + }, + "post": { + "description": "Creates a new user account and immediately adds them to the specified organization. Use this endpoint when you want to create a user and grant them access to an organization in a single operation. You can provide user profile information, assign roles, and configure membership metadata. The user receives an activation email unless this feature is disabled in the organization settings.", + "tags": [ + "Users" + ], + "summary": "Create new user in organization", + "operationId": "UserService_CreateUserAndMembership", + "parameters": [ + { + "schema": { + "type": "string" + }, + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "boolean" + }, + "description": "If true, sends an activation email to the user. Defaults to true.", + "name": "send_invitation_email", + "in": "query" + } + ], + "responses": { + "201": { + "description": "User created successfully. Returns the created user object, including system-generated identifiers and timestamps", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/usersCreateUserAndMembershipResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const {\n user } = await scalekit.user.\n createUserAndMembership(\"org_123\", {\n\temail: \"user@example.com\",\n\texternalId: \"ext_12345a67b89c\",\n\tmetadata: { department: \"engineering\", \n\t location: \"nyc-office\" },\n\tuserProfile: {\n\t\tfirstName: \"John\",\n\t\tlastName: \"Doe\",\n\t},\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "# Create user with membership \nuser = CreateUser(\n email=\"john.doe@example.com\",\n external_id=\"ext_john_123\", # Optional\n user_profile={\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"name\": \"John Doe\",\n \"locale\": \"en-US\",\n \"phone_number\": \"+14155552671\"\n },\n membership={\n \"roles\": [{\"name\": \"member\"}] \n }\n)\n\n# Create user and membership in organization\nresponse = scalekit_client.users.create_user_and_membership(\n organization_id=\"your_org_id\",\n user=user,\n send_invitation_email=True # Set to False if you don't want to send\nemail )\n\n user_id = response[0].user.id" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "newUser := &usersv1.CreateUser{\n Email: \"user@example.com\",\n ExternalId: \"ext_12345a67b89c\",\n Metadata: map[string]string{\n \"department\": \"engineering\",\n \"location\": \"nyc-office\",\n },\n UserProfile: &usersv1.CreateUserProfile{\n FirstName: \"John\",\n LastName: \"Doe\",\n },\n}\ncuResp, \n err := scalekitClient.User().CreateUserAndMembership(ctx, \"org_123\",\nnewUser, false) if err != nil { /* handle error */ }" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "CreateUser createUser = CreateUser.newBuilder()\n .setEmail(\"user@example.com\")\n .setExternalId(\"ext_12345a67b89c\")\n .putMetadata(\"department\", \"engineering\")\n .putMetadata(\"location\", \"nyc-office\")\n .setUserProfile(\n CreateUserProfile.newBuilder()\n .setFirstName(\"John\")\n .setLastName(\"Doe\")\n .build())\n .build();\nCreateUserAndMembershipRequest cuReq = CreateUserA\n ndMembershipRequest.newBuilder()\n .setUser(createUser)\n .build();\nCreateUserAndMembershipResponse cuResp = users.\n createUserAndMembership(\"org_123\", cuReq);\nSystem.out.println(cuResp.getUser().getId());" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/usersCreateUser" + } + } + }, + "required": true + } + } + }, + "/api/v1/organizations/{organization_id}/users/{user_id}/permissions": { + "get": { + "description": "Retrieves all permissions a user has access to within a specific organization. This includes permissions from direct role assignments and inherited permissions from role hierarchy.", + "tags": [ + "Users" + ], + "summary": "List user permissions", + "operationId": "UserService_ListUserPermissions", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier for the organization", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique identifier for the user", + "name": "user_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully retrieved the list of permissions for the user", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/usersListUserPermissionsResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const { permissions } = await scalekit.user.listUserPermissions(\"org_123\", \"usr_123\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "resp = scalekit_client.users.list_user_permissions(\n organization_id=\"org_123\",\n user_id=\"usr_123\",\n)\npermissions = resp.permissions" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.User().ListUserPermissions(ctx, \"org_123\", \"usr_123\")\nif err != nil {\n // handle error\n}\npermissions := resp.Permissions" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ListUserPermissionsResponse resp = scalekitClient.users().listUserPermissions(\"org_123\", \"usr_123\");\nList permissions = resp.getPermissionsList();" + } + ] + } + }, + "/api/v1/organizations/{organization_id}/users/{user_id}/roles": { + "get": { + "description": "Retrieves all roles assigned to a user within a specific organization. This includes both direct role assignments and inherited roles from role hierarchy.", + "tags": [ + "Users" + ], + "summary": "List user roles", + "operationId": "UserService_ListUserRoles", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier for the organization", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique identifier for the user", + "name": "user_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully retrieved the list of roles assigned to the user", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/usersListUserRolesResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const { roles } = await scalekit.user.listUserRoles(\"org_123\", \"usr_123\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "resp = scalekit_client.users.list_user_roles(\n organization_id=\"org_123\",\n user_id=\"usr_123\",\n)\nroles = resp.roles" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.User().ListUserRoles(ctx, \"org_123\", \"usr_123\")\nif err != nil {\n // handle error\n}\nroles := resp.Roles" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ListUserRolesResponse resp = scalekitClient.users().listUserRoles(\"org_123\", \"usr_123\");\nList roles = resp.getRolesList();" + } + ] + } + }, + "/api/v1/organizations/{organization_id}/users:search": { + "get": { + "description": "Searches for users within a specific organization by email address, user ID, or external ID. The query must be at least 3 characters and is case-insensitive. Scopes results strictly to the given organization. Returns a paginated list of matching users with up to 30 results per page. Use the next_page_token from the response to retrieve subsequent pages.", + "tags": [ + "Users" + ], + "summary": "Search organization users", + "operationId": "UserService_SearchOrganizationUsers", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier of the organization to search within. Must start with 'org_' and be 1-32 characters long.", + "name": "organization_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string", + "minLength": 3, + "maxLength": 100 + }, + "description": "Search term to match against user email, IDs, or external IDs. Must be at least 3 characters. Case insensitive.", + "name": "query", + "in": "query", + "required": true + }, + { + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 30 + }, + "description": "Maximum number of users to return per page. Value must be between 1 and 30.", + "name": "page_size", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Token from a previous response for pagination. Provide this to retrieve the next page of results.", + "name": "page_token", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Matching users within the organization returned; includes pagination cursors for navigating large result sets.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/usersSearchOrganizationUsersResponse" + } + } + } + }, + "400": { + "description": "Bad Request - query must be at least 3 characters and no more than 100 characters, and organization_id must be a valid org_ prefixed identifier.", + "content": { + "application/json": { + "schema": {} + } + } + }, + "404": { + "description": "Not Found - organization not found.", + "content": { + "application/json": { + "schema": {} + } + } + } + } + } + }, + "/api/v1/organizations:external/{external_id}": { + "get": { + "description": "Retrieves organization details by External ID, including name, region, metadata, and settings", + "tags": [ + "Organizations" + ], + "summary": "Get organization details by external Id", + "operationId": "OrganizationService_GetOrganizationByExternalId", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier that links an Organization Object to your app's tenant, stored as an External ID", + "name": "external_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Unique scalekit-generated identifier that uniquely references an organization", + "name": "id", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Returns the complete organization object with ID, display name, settings, external ID and metadata", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/organizationsGetOrganizationResponse" + } + } + } + }, + "400": { + "description": "Invalid request - external ID is empty or the caller's organization claim does not match", + "content": { + "application/json": { + "schema": {} + } + } + }, + "404": { + "description": "Organization not found - no organization exists with the specified external ID", + "content": { + "application/json": { + "schema": {} + } + } + } + } + } + }, + "/api/v1/passwordless/email/resend": { + "post": { + "description": "Resend a verification email if the user didn't receive it or if the previous code/link has expired", + "tags": [ + "Magic link & OTP" + ], + "summary": "Resend passwordless email", + "operationId": "PasswordlessService_ResendPasswordlessEmail", + "responses": { + "200": { + "description": "Successfully resent the passwordless authentication email. Returns updated authentication request details with new expiration time.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/passwordlessSendPasswordlessResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const { authRequestId } = sendResponse;\nconst resendResponse = await scalekit.passwordless.resendPasswordlessEmail(\n\n\tauthRequestId\n\n);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "resend_response = scalekit_client.passwordless.resend_passwordless_email(\n auth_request_id=auth_request_id,\n)\n\n# New auth request ID from resend\nnew_auth_request_id = resend_response[0].auth_request_id" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resendResponse, err := scalekitClient.Passwordless().ResendPasswordlessEmail(\n ctx,\n authRequestId,\n)\n\nif err != nil {\n // Handle error\n return\n}" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "SendPasswordlessResponse resendResponse = passwordlessClient.resendPasswordlessEmail(authRequestId);" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/passwordlessResendPasswordlessRequest" + } + } + }, + "required": true + } + } + }, + "/api/v1/passwordless/email/send": { + "post": { + "description": "Send a verification email containing either a verification code (OTP), magic link, or both to a user's email address", + "tags": [ + "Magic link & OTP" + ], + "summary": "Send passwordless email", + "operationId": "PasswordlessService_SendPasswordlessEmail", + "responses": { + "200": { + "description": "Successfully sent passwordless authentication email. Returns the authentication request details including expiration time and auth request ID", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/passwordlessSendPasswordlessResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const response = await scalekit.passwordless.sendPasswordlessEmail(\n\t\"john.doe@example.com\",\n\t{\n\t\ttemplate: \"SIGNIN\",\n\t\texpiresIn: 100,\n\t\tmagiclinkAuthUri: \"https://www.google.com\",\n\t\ttemplateVariables: {\n\t\t\temployeeID: \"EMP523\",\n\t\t\tteamName: \"Alpha Team\",\n\t\t\tsupportEmail: \"support@yourcompany.com\",\n\t\t},\n\t}\n);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "response = scalekit_client.passwordless.send_passwordless_email(\n email=\"john.doe@example.com\",\n template=\"SIGNIN\", # or \"SIGNUP\", \"UNSPECIFIED\"\n expires_in=100,\n magiclink_auth_uri=\"https://www.google.com\",\n template_variables={\n \"employeeID\": \"EMP523\",\n \"teamName\": \"Alpha Team\",\n \"supportEmail\": \"support@yourcompany.com\",\n },\n)\n\n# Extract auth request ID from response\nauth_request_id = response[0].auth_request_id" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "templateType := scalekit.TemplateTypeSignin\nresponse, err := scalekitClient.Passwordless().SendPasswordlessEmail(\n ctx,\n \"john.doe@example.com\",\n &scalekit.SendPasswordlessOptions{\n Template: &templateType,\n ExpiresIn: 100,\n MagiclinkAuthUri: \"https://www.google.com\",\n TemplateVariables: map[string]string{\n \"employeeID\": \"EMP523\",\n \"teamName\": \"Alpha Team\",\n \"supportEmail\": \"support@yourcompany.com\",\n },\n },\n)\n\nif err != nil {\n // Handle error\n return\n}\n\nauthRequestId := response.AuthRequestId" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "TemplateType templateType = TemplateType.SIGNIN;\nMap templateVariables = new HashMap<>();\ntemplateVariables.put(\"employeeID\", \"EMP523\");\ntemplateVariables.put(\"teamName\", \"Alpha Team\");\ntemplateVariables.put(\"supportEmail\", \"support@yourcompany.com\");\n\nSendPasswordlessOptions options = new SendPasswordlessOptions();\noptions.setTemplate(templateType);\noptions.setExpiresIn(100);\noptions.setMagiclinkAuthUri(\"https://www.example.com\");\noptions.setTemplateVariables(templateVariables);\n\nSendPasswordlessResponse response = passwordlessClient.sendPasswordlessEmail(\n \"john.doe@example.com\",\n options\n);\n\nString authRequestId = response.getAuthRequestId();" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/passwordlessSendPasswordlessRequest" + } + } + }, + "required": true + } + } + }, + "/api/v1/passwordless/email/verify": { + "post": { + "description": "Verify a user's identity using either a verification code or magic link token", + "tags": [ + "Magic link & OTP" + ], + "summary": "Verify passwordless email", + "operationId": "PasswordlessService_VerifyPasswordlessEmail", + "responses": { + "200": { + "description": "Successfully verified the passwordless authentication. Returns user email", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/passwordlessVerifyPasswordLessResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const { authRequestId } = sendResponse;\nconst verifyResponse = await scalekit.passwordless.verifyPasswordlessEmail(\n\n\t// Verification Code (OTP)\n\n\t{ code: \"123456\" },\n\n\t// Magic Link Token\n\n\t{ linkToken: link_token },\n\n\tauthRequestId\n\n);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "# Verify with OTP code\nverify_response = scalekit_client.passwordless.verify_passwordless_email(\n code=\"123456\", # OTP code received via email\n auth_request_id=auth_request_id,\n)\n\n# Verify with magic link token\nverify_response = scalekit_client.passwordless.verify_passwordless_email(\n link_token=link_token, # Magic link token from URL\n)\n\n# User verified successfully\nuser_email = verify_response[0].email" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "// Verify with OTP code\nverifyResponse, err := scalekitClient.Passwordless().VerifyPasswordlessEmail(\n ctx,\n &scalekit.VerifyPasswordlessOptions{\n Code: \"123456\", // OTP code\n AuthRequestId: authRequestId,\n },\n)\n\nif err != nil {\n // Handle error\n return\n}\n\n// Verify with magic link token\nverifyResponse, err := scalekitClient.Passwordless().VerifyPasswordlessEmail(\n ctx,\n &scalekit.VerifyPasswordlessOptions{\n LinkToken: linkToken, // Magic link token\n },\n)\n\nif err != nil {\n // Handle error\n return\n}\n\n// User verified successfully\nuserEmail := verifyResponse.Email" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "// Verify with OTP code\nVerifyPasswordlessOptions verifyOptions = new VerifyPasswordlessOptions();\nverifyOptions.setCode(\"123456\"); // OTP code\nverifyOptions.setAuthRequestId(authRequestId);\n\nVerifyPasswordLessResponse verifyResponse = passwordlessClient.verifyPasswordlessEmail(verifyOptions);\n\n// User verified successfully\nString userEmail = verifyResponse.getEmail();\n\n// Verify with magic link token\nVerifyPasswordlessOptions verifyOptions = new VerifyPasswordlessOptions();\nverifyOptions.setLinkToken(linkToken); // Magic link token\n\nVerifyPasswordLessResponse verifyResponse = passwordlessClient.verifyPasswordlessEmail(verifyOptions);\n\n// User verified successfully\nString userEmail = verifyResponse.getEmail();" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/passwordlessVerifyPasswordLessRequest" + } + } + }, + "required": true + } + } + }, + "/api/v1/permissions": { + "get": { + "description": "Retrieves a comprehensive, paginated list of all permissions available within the environment. Use this endpoint to view all permission definitions for auditing, role management, or understanding the complete set of available access controls. The response includes pagination tokens to navigate through large sets of permissions efficiently. Each permission object contains the permission name, description, creation time, and last update time. This operation is useful for building permission selection interfaces, auditing permission usage, or understanding the scope of available access controls in your RBAC system.", + "tags": [ + "Permissions" + ], + "summary": "List all permissions", + "operationId": "RolesService_ListPermissions", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Page token to retrieve next page of results", + "name": "page_token", + "in": "query" + }, + { + "schema": { + "type": "integer", + "format": "int64" + }, + "description": "Number of permissions to return per page (max 100)", + "name": "page_size", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "SCALEKIT", + "ENVIRONMENT" + ] + }, + "description": "Filter permissions by type: ALL, SCALEKIT, or ENVIRONMENT, where SCALEKIT are predefined Scalekit permissions and ENVIRONMENT are custom permissions created in the environment, default is ALL", + "name": "type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved the list of permissions. Returns a paginated list of permission objects with metadata and pagination tokens for navigation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesListPermissionsResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.permission.listPermissions();" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "res = scalekit_client.permissions.list_permissions()" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Permission().ListPermissions(ctx)\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ListPermissionsResponse res = scalekitClient.permissions().listPermissions();" + } + ] + }, + "post": { + "description": "Creates a new permission that represents a specific action users can perform within the environment. Use this endpoint to define granular access controls for your RBAC system. You can provide a unique permission name following the format 'action:resource' (for example, 'read:documents', 'write:users') and an optional description explaining the permission's purpose. The permission name must be unique across the environment and follows alphanumeric naming conventions with colons and underscores. Returns the created permission object including system-generated ID and timestamps.", + "tags": [ + "Permissions" + ], + "summary": "Create new permission", + "operationId": "RolesService_CreatePermission", + "responses": { + "201": { + "description": "Permission created successfully. Returns the complete permission object with system-generated ID, name, description, and timestamps.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesCreatePermissionResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.permission.createPermission({\n name: \"read:users\",\n description: \"Allows reading users\"\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "from scalekit.v1.roles.roles_pb2 import CreatePermission\n\npermission = CreatePermission(\n name=\"read:users\",\n description=\"Allows reading users\"\n)\n\nscalekit_client.permissions.create_permission(permission=permission)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Permission().CreatePermission(ctx, &rolesv1.CreatePermission{\n\n\tName: \"read:users\",\n\n\tDescription: \"Allows reading users\",\n\n})\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "CreatePermissionResponse res = scalekitClient.permissions().createPermission(\n CreatePermissionRequest.newBuilder()\n .setPermission(\n CreatePermission.newBuilder()\n .setName(\"read:users\")\n .setDescription(\"Allows reading users\")\n .build()\n )\n .build()\n);" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/v1rolesCreatePermission" + } + } + }, + "required": true + } + } + }, + "/api/v1/permissions/{permission_name}": { + "get": { + "description": "Retrieves complete information for a specific permission by its unique name identifier. Use this endpoint to view permission details including description, creation time, and last update time. Provide the permission name in the path parameter following the format 'action:resource' (for example, 'read:documents'). This operation is useful for auditing permission definitions, understanding permission purposes, or verifying permission existence before assignment. Returns the complete permission object with all metadata and system-generated timestamps.", + "tags": [ + "Permissions" + ], + "summary": "Retrieve permission details", + "operationId": "RolesService_GetPermission", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Name of the permission", + "name": "permission_name", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully retrieved permission details. Returns the complete permission object including name, description, creation time, and update time.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesGetPermissionResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.permission.getPermission(\"read:users\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "res = scalekit_client.permissions.get_permission(\n permission_name=\"read:users\"\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Permission().GetPermission(ctx, \"read:users\")\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "GetPermissionResponse res = scalekitClient.permissions().getPermission(\"read:users\");" + } + ] + }, + "put": { + "description": "Modifies an existing permission's attributes including description and metadata. Use this endpoint to update permission descriptions or clarify permission purposes after creation. The permission is identified by its unique name in the path parameter, and only the fields you specify in the request body will be updated. Note that the permission name itself cannot be changed as it serves as the immutable identifier. This operation is useful for maintaining clear documentation of permission purposes or updating descriptions to reflect changes in system functionality. Returns the updated permission object with modified timestamps.", + "tags": [ + "Permissions" + ], + "summary": "Update permission details", + "operationId": "RolesService_UpdatePermission", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Name of the permission", + "name": "permission_name", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Permission updated successfully. Returns the modified permission object with updated description and timestamps.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesUpdatePermissionResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.permission.updatePermission(\"read:users\", {\n name: \"read:users\",\n description: \"Allows reading user resources\"\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "from scalekit.v1.roles.roles_pb2 import CreatePermission\n\nscalekit_client.permissions.update_permission(\n permission_name=\"read:users\",\n permission=CreatePermission(\n name=\"read:users\",\n description=\"Allows reading user resources\"\n )\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Permission().UpdatePermission(ctx, \"read:users\", &rolesv1.CreatePermission{\n Name: \"read:users\",\n Description: \"Allows reading user resources\",\n})\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "UpdatePermissionResponse res = scalekitClient.permissions().updatePermission(\n \"read:users\",\n UpdatePermissionRequest.newBuilder()\n .setPermission(\n CreatePermission.newBuilder()\n .setName(\"read:users\")\n .setDescription(\"Allows reading user resources\")\n .build()\n )\n .build()\n);" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/v1rolesCreatePermission" + } + } + }, + "required": true + } + }, + "delete": { + "description": "Permanently removes a permission from the environment using its unique name identifier. Use this endpoint when you need to clean up unused permissions or remove access controls that are no longer relevant. The permission is identified by its name in the path parameter following the format 'action:resource'. This operation cannot be undone, so ensure no active roles depend on the permission before deletion. If the permission is currently assigned to any roles, you may need to remove those assignments first or update the roles to use alternative permissions. Returns no content on successful deletion.", + "tags": [ + "Permissions" + ], + "summary": "Delete permission", + "operationId": "RolesService_DeletePermission", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Name of the permission", + "name": "permission_name", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Permission successfully deleted. No content returned.", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.permission.deletePermission(\"read:users\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "scalekit_client.permissions.delete_permission(\n permission_name=\"read:users\"\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "err := scalekitClient.Permission().DeletePermission(ctx, \"read:users\")\nif err != nil { /* handle err */ }" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "scalekitClient.permissions().deletePermission(\"read:users\");" + } + ] + } + }, + "/api/v1/roles": { + "get": { + "description": "Retrieves a comprehensive list of all roles available within the specified environment including organization roles. Use this endpoint to view all role definitions, including custom roles and their configurations. You can optionally include permission details for each role to understand their capabilities. This is useful for role management, auditing organization access controls, or understanding the available access levels within the organization.", + "tags": [ + "Roles" + ], + "summary": "List all roles in environment", + "operationId": "RolesService_ListRoles", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Include additional data in the response. Valid values: 'permissions' (direct permissions only), 'permissions:all' (includes inherited permissions from role hierarchy)", + "name": "include", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved list of roles. Returns all roles with their metadata and optionally their permissions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesListRolesResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.role.listRoles();" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "res = scalekit_client.roles.list_roles()" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Role().ListRoles(ctx)\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ListRolesResponse res = scalekitClient.roles().listRoles();" + } + ] + }, + "post": { + "description": "Creates a new role within the environment with specified permissions and metadata. Use this endpoint to define custom roles that can be assigned to users or groups. You can create hierarchical roles by extending existing roles, assign specific permissions, and configure display information. Roles are the foundation of your access control system and determine what actions users can perform.", + "tags": [ + "Roles" + ], + "summary": "Create new role in environment", + "operationId": "RolesService_CreateRole", + "responses": { + "201": { + "description": "Role created successfully. Returns the complete role object with system-generated ID and timestamps.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesCreateRoleResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.role.createRole({\n name: \"admin\",\n displayName: \"Admin\",\n description: \"Environment-level role\",\n extends: \"base_role\", // optional\n permissions: [\"read:users\"] // optional\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "from scalekit.v1.roles.roles_pb2 import CreateRole\n\nrole = CreateRole(\n name=\"admin\",\n display_name=\"Admin\",\n description=\"Environment-level role\",\n extends=\"base_role\", # optional\n permissions=[\"read:users\"] # optional\n)\n\nscalekit_client.roles.create_role(role=role)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Role().CreateRole(ctx, &rolesv1.CreateRole{\n\n\tName: \"admin\",\n\n\tDisplayName: \"Admin\",\n\n\tDescription: \"Environment-level role\",\n\n\tExtends: proto.String(\"base_role\"), // optional\n\n\tPermissions: []string{\"read:users\"}, // optional\n\n})" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "CreateRoleResponse res = scalekitClient.roles().createRole(\n CreateRoleRequest.newBuilder()\n .setRole(\n CreateRole.newBuilder()\n .setName(\"admin\")\n .setDisplayName(\"Admin\")\n .setDescription(\"Environment-level role\")\n // .setExtends(\"base_role\") // optional\n // .addPermissions(\"read:users\") // optional\n .build()\n )\n .build()\n);" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Role configuration details including name, display name, description, permissions, and inheritance settings.", + "$ref": "#/components/schemas/v1rolesCreateRole", + "examples": [ + { + "description": "Can edit content", + "display_name": "Content Editor", + "name": "content_editor", + "permissions": [ + "read:content", + "write:content" + ] + } + ] + } + } + }, + "required": true + } + } + }, + "/api/v1/roles/default": { + "patch": { + "description": "Updates the default creator and member roles for the current environment. Use this endpoint to configure which roles are automatically assigned to new users when they join the environment. You can specify role names for both creator and member default roles. The system will validate that the specified roles exist and update the environment settings accordingly. Returns the updated default role objects including their complete role information and permissions.", + "tags": [ + "Roles" + ], + "summary": "Set default creator and member roles", + "operationId": "RolesService_UpdateDefaultRoles2", + "responses": { + "200": { + "description": "Default roles updated successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesUpdateDefaultRolesResponse" + } + } + } + } + }, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesUpdateDefaultRolesRequest" + } + } + }, + "required": true + } + } + }, + "/api/v1/roles/{role_name}": { + "get": { + "description": "Retrieves complete information for a specific role including metadata and inheritance details (base role and dependent role count). Use this endpoint to audit role configuration and understand the role's place in the hierarchy. To view the role's permissions, use the ListRolePermissions endpoint.", + "tags": [ + "Roles" + ], + "summary": "Get role details", + "operationId": "RolesService_GetRole", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique name identifier of the role to retrieve. Must be alphanumeric with underscores, 1-64 characters.", + "name": "role_name", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Include additional data in the response. Valid values: 'permissions' (direct permissions only), 'permissions:all' (includes inherited permissions from role hierarchy)", + "name": "include", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved role details. Returns the role object including metadata and inheritance details. Permissions are not included.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesGetRoleResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.role.getRole(\"admin\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "res = scalekit_client.roles.get_role(role_name=\"admin\")" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Role().GetRole(ctx, \"admin\")\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "GetRoleResponse res = scalekitClient.roles().getRole(\"admin\");" + } + ] + }, + "put": { + "description": "Modifies an existing role's properties including display name, description, permissions, and inheritance. Use this endpoint to update role metadata, change permission assignments, or modify role hierarchy. Only the fields you specify will be updated, leaving other properties unchanged. When updating permissions, the new list replaces all existing permissions for the role.", + "tags": [ + "Roles" + ], + "summary": "Update role information", + "operationId": "RolesService_UpdateRole", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique name identifier of the role to update. Must be alphanumeric with underscores, 1-64 characters.", + "name": "role_name", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Role updated successfully. Returns the modified role object with updated timestamps.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesUpdateRoleResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.role.updateRole(\"admin\", {\n displayName: \"Admin (Updated)\",\n description: \"Updated description\"\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "from scalekit.v1.roles.roles_pb2 import UpdateRole\n\nscalekit_client.roles.update_role(\n role_name=\"admin\",\n role=UpdateRole(\n display_name=\"Admin (Updated)\",\n description=\"Updated description\"\n )\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Role().UpdateRole(ctx, \"admin\", &rolesv1.UpdateRole{\n DisplayName: \"Admin (Updated)\",\n Description: \"Updated description\",\n})\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "UpdateRoleResponse res = scalekitClient.roles().updateRole(\n \"admin\",\n UpdateRoleRequest.newBuilder()\n .setRole(\n UpdateRole.newBuilder()\n .setDisplayName(\"Admin (Updated)\")\n .setDescription(\"Updated description\")\n .build()\n )\n .build()\n);" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "Role fields to update. Only specified fields will be modified.", + "$ref": "#/components/schemas/v1rolesUpdateRole", + "examples": [ + { + "description": "Can edit and approve content", + "display_name": "Senior Editor" + } + ] + } + } + }, + "required": true + } + }, + "delete": { + "description": "Permanently removes a role from the environment and reassigns users who had that role to a different role. Use this endpoint when you need to clean up unused roles or restructure your access control system. The role cannot be deleted if it has dependent roles (roles that extend it) unless you specify a replacement role. If users are assigned to the role being deleted, you must provide a reassign_role_name to move those users to a different role before deletion can proceed. This action cannot be undone, so ensure no critical users depend on the role before deletion.", + "tags": [ + "Roles" + ], + "summary": "Delete role and reassign users", + "operationId": "RolesService_DeleteRole", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique name identifier of the role to delete. Must be alphanumeric with underscores, 1-64 characters.", + "name": "role_name", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Role name to reassign users to when deleting this role", + "name": "reassign_role_id", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Role name to reassign users to when deleting this role", + "name": "reassign_role_name", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Role successfully deleted and users reassigned. No content returned.", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "// Basic delete\nawait scalekit.role.deleteRole(\"admin\");\n\n// With reassignment\nawait scalekit.role.deleteRole(\"admin\", \"member\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "# Basic delete\nscalekit_client.roles.delete_role(role_name=\"admin\")\n\n# With reassignment\nscalekit_client.roles.delete_role(\n role_name=\"admin\",\n reassign_role_name=\"member\"\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "// Basic delete\nerr := scalekitClient.Role().DeleteRole(ctx, \"admin\")\nif err != nil { /* handle err */ }\n\n// With reassignment\nerr = scalekitClient.Role().DeleteRole(ctx, \"admin\", \"member\")" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "// Basic delete\nscalekitClient.roles().deleteRole(\"admin\");\n\n// With reassignment\nscalekitClient.roles().deleteRole(\"admin\", \"member\");" + } + ] + } + }, + "/api/v1/roles/{role_name}/base": { + "delete": { + "description": "Removes the base role inheritance relationship for a specified role, effectively eliminating all inherited permissions from the base role. Use this endpoint when you want to break the hierarchical relationship between roles and remove inherited permissions. The role will retain only its directly assigned permissions after this operation. This action cannot be undone, so ensure the role has sufficient direct permissions before removing inheritance. Returns no content on successful removal of the base relationship.", + "tags": [ + "Roles" + ], + "summary": "Delete role inheritance relationship", + "operationId": "RolesService_DeleteRoleBase", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique name identifier of the role whose base inheritance relationship should be removed. Must be alphanumeric with underscores, 1-64 characters.", + "name": "role_name", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Base role inheritance relationship successfully removed. The role now has only its directly assigned permissions.", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.role.deleteRoleBase(\"senior_editor\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "scalekit_client.roles.delete_role_base(role_name=\"senior_editor\")" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "err := scalekitClient.Role().DeleteRoleBase(ctx, \"senior_editor\")\nif err != nil {\n // handle error\n}" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "scalekitClient.roles().deleteRoleBase(\"senior_editor\");" + } + ] + } + }, + "/api/v1/roles/{role_name}/dependents": { + "get": { + "description": "Retrieves all roles that directly extend the specified base role through inheritance. Use this endpoint to understand the role hierarchy and identify which roles inherit permissions from a particular base role. Provide the base role name as a path parameter, and the response will include all dependent roles with their metadata and permission information. This operation is useful for auditing role inheritance relationships, understanding the impact of changes to base roles, or managing role hierarchies effectively. Returns a list of dependent role objects including their names, display names, descriptions, and permission details.", + "tags": [ + "Roles" + ], + "summary": "List dependent roles", + "operationId": "RolesService_ListDependentRoles", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Name of the base role", + "name": "role_name", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully retrieved dependent roles. Returns a list of all roles that extend the specified base role, including their metadata and permission information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesListDependentRolesResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.role.listDependentRoles(\"admin\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "res = scalekit_client.roles.list_dependent_roles(role_name=\"admin\")" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Role().ListDependentRoles(ctx, \"admin\")\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ListDependentRolesResponse res = scalekitClient.roles().listDependentRoles(\"admin\");" + } + ] + } + }, + "/api/v1/roles/{role_name}/permissions": { + "get": { + "description": "Retrieves all permissions directly assigned to the specified role, excluding permissions inherited from base roles. Use this endpoint to view the explicit permission assignments for a role, which is useful for understanding direct role capabilities, auditing permission assignments, or managing role-permission relationships. Provide the role name as a path parameter, and the response will include only the permissions that are directly assigned to that role. This operation does not include inherited permissions from role hierarchies - use ListEffectiveRolePermissions to see the complete set of permissions including inheritance. Returns a list of permission objects with their names, descriptions, and assignment metadata.", + "tags": [ + "Roles" + ], + "summary": "List permissions for role", + "operationId": "RolesService_ListRolePermissions", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Name of the role", + "name": "role_name", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully retrieved role permissions. Returns a list of all permissions directly assigned to the specified role, excluding inherited permissions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesListRolePermissionsResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.permission.listRolePermissions(\"admin\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "res = scalekit_client.permissions.list_role_permissions(role_name=\"admin\")" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Permission().ListRolePermissions(ctx, \"admin\")\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ListRolePermissionsResponse res = scalekitClient.permissions().listRolePermissions(\"admin\");" + } + ] + }, + "post": { + "description": "Adds one or more permissions to the specified role while preserving existing permission assignments. Use this endpoint to grant additional capabilities to a role without affecting its current permission set. Provide the role name as a path parameter and a list of permission names in the request body. The system will validate that all specified permissions exist in the environment and add them to the role. Existing permission assignments remain unchanged, making this operation safe for incremental permission management. This is useful for gradually expanding role capabilities or adding new permissions as your system evolves. Returns the updated list of all permissions now assigned to the role.", + "tags": [ + "Roles" + ], + "summary": "Add permissions to role", + "operationId": "RolesService_AddPermissionsToRole", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Name of the role", + "name": "role_name", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Permissions added to role successfully. Returns the complete list of all permissions now assigned to the role, including both existing and newly added permissions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesAddPermissionsToRoleResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.permission.addPermissionsToRole(\"role_admin\", [\"perm.read\", \"perm.write\"]);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "scalekit_client.permissions.add_permissions_to_role(\n role_name=\"role_admin\",\n permission_names=[\"perm.read\", \"perm.write\"]\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Permission().AddPermissionsToRole(ctx, \"role_admin\", []string{\"perm.read\", \"perm.write\"})" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "AddPermissionsToRoleResponse res = scalekitClient.permissions().addPermissionsToRole(\n \"role_admin\",\n AddPermissionsToRoleRequest.newBuilder()\n .addPermissionNames(\"perm.read\")\n .addPermissionNames(\"perm.write\")\n .build()\n);" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RolesServiceAddPermissionsToRoleBody" + } + } + }, + "required": true + } + } + }, + "/api/v1/roles/{role_name}/permissions/{permission_name}": { + "delete": { + "description": "Removes a specific permission from the specified role, revoking that capability from all users assigned to the role. Use this endpoint to restrict role capabilities or remove unnecessary permissions. Provide both the role name and permission name as path parameters. This operation only affects the direct permission assignment and does not impact permissions inherited from base roles. If the permission is inherited through role hierarchy, you may need to modify the base role instead. This is useful for fine-tuning role permissions, implementing least-privilege access controls, or removing deprecated permissions. Returns no content on successful removal.", + "tags": [ + "Roles" + ], + "summary": "Remove permission from role", + "operationId": "RolesService_RemovePermissionFromRole", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Name of the role", + "name": "role_name", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Name of the permission to remove", + "name": "permission_name", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Permission removed from role successfully. No content returned.", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.permission.removePermissionFromRole(\"admin\", \"read:users\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "scalekit_client.permissions.remove_permission_from_role(\n role_name=\"admin\",\n permission_name=\"read:users\"\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "err := scalekitClient.Permission().RemovePermissionFromRole(ctx, \"admin\", \"read:users\")\nif err != nil { /* handle err */ }" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "scalekitClient.permissions().removePermissionFromRole(\"admin\", \"read:users\");" + } + ] + } + }, + "/api/v1/roles/{role_name}/permissions:all": { + "get": { + "description": "Retrieves the complete set of effective permissions for a role, including both directly assigned permissions and permissions inherited from base roles through the role hierarchy. Use this endpoint to understand the full scope of capabilities available to users assigned to a specific role. Provide the role name as a path parameter, and the response will include all permissions that apply to the role, accounting for inheritance relationships. This operation is essential for auditing role capabilities, understanding permission inheritance, or verifying the complete access scope before role assignment. Returns a comprehensive list of permission names representing the full set of effective permissions for the specified role.", + "tags": [ + "Roles" + ], + "summary": "List effective permissions for role", + "operationId": "RolesService_ListEffectiveRolePermissions", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Name of the role", + "name": "role_name", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully retrieved effective permissions. Returns the complete list of all permissions that apply to the role, including both direct assignments and inherited permissions from base roles.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesListEffectiveRolePermissionsResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const { permissions } = await scalekit.permission.listEffectiveRolePermissions(\"senior_editor\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "response = scalekit_client.permissions.list_effective_role_permissions(role_name=\"senior_editor\")\npermissions = response.permissions" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Permission().ListEffectiveRolePermissions(ctx, \"senior_editor\")\nif err != nil {\n // handle error\n}\npermissions := resp.Permissions" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ListEffectiveRolePermissionsResponse response = scalekitClient.permissions().listEffectiveRolePermissions(\"senior_editor\");\nList permissions = response.getPermissionsList();" + } + ] + } + }, + "/api/v1/roles/{role_name}/users:count": { + "get": { + "description": "Retrieves the total number of users currently assigned to the specified role within the environment. Use this endpoint to monitor role usage, enforce user limits, or understand the scope of role assignments. Provide the role's unique name as a path parameter, and the response will include the current user count for that role. This operation is read-only and does not modify any data or user assignments. The count reflects all users who have the role either directly assigned or inherited through organization membership. This information is useful for capacity planning, security auditing, or understanding the impact of role changes across your user base.", + "tags": [ + "Roles" + ], + "summary": "Retrieve user count for role", + "operationId": "RolesService_GetRoleUsersCount", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique name of the role", + "name": "role_name", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully retrieved user count for the specified role. Returns the total number of users currently assigned to the role, including both direct assignments and inherited assignments.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesGetRoleUsersCountResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.role.getRoleUsersCount(\"admin\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "res = scalekit_client.roles.get_role_users_count(role_name=\"admin\")" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Role().GetRoleUsersCount(ctx, \"admin\")\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "GetRoleUsersCountResponse res = scalekitClient.roles().getRoleUsersCount(\"admin\");" + } + ] + } + }, + "/api/v1/roles:set_defaults": { + "patch": { + "description": "Updates the default creator and member roles for the current environment. Use this endpoint to configure which roles are automatically assigned to new users when they join the environment. You can specify role names for both creator and member default roles. The system will validate that the specified roles exist and update the environment settings accordingly. Returns the updated default role objects including their complete role information and permissions.", + "tags": [ + "Roles" + ], + "summary": "Set default creator and member roles", + "operationId": "RolesService_UpdateDefaultRoles", + "responses": { + "200": { + "description": "Default roles updated successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesUpdateDefaultRolesResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.role.updateDefaultRoles({\n defaultMemberRole: \"member\"\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "from scalekit.v1.roles.roles_pb2 import UpdateDefaultRolesRequest\n\nres = scalekit_client.roles.update_default_roles(\n default_roles=UpdateDefaultRolesRequest(\n default_member_role=\"member\"\n )\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Role().UpdateDefaultRoles(ctx, \"member\")\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "UpdateDefaultRolesResponse res = scalekitClient.roles().updateDefaultRoles(\n UpdateDefaultRolesRequest.newBuilder()\n .setDefaultMemberRole(\"member\")\n .build()\n);" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/rolesUpdateDefaultRolesRequest" + } + } + }, + "required": true + } + } + }, + "/api/v1/sessions/{session_id}": { + "get": { + "description": "Retrieves comprehensive details for a specific user session including authentication status, device information, and expiration timelines. Use this endpoint to fetch current session metadata for security audits, session validation, or to display session information in user account management interfaces. Returns all session properties including the user ID, authenticated organizations, device details with browser/OS information, IP address and geolocation, and all relevant timestamps (creation, last activity, idle expiration, absolute expiration, and actual expiration if applicable).", + "tags": [ + "Sessions" + ], + "summary": "Get session details", + "operationId": "SessionService_GetSession", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier for the session. Must start with 'ses_' prefix.", + "name": "session_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully retrieved session details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/sessionsSessionDetails" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.session.getSession(\"ses_123456789\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "res = scalekit_client.sessions.get_session(session_id=\"ses_123456789\")" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Session().GetSession(ctx, \"ses_123456789\")\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "SessionDetails res = scalekitClient.sessions().getSession(\"ses_123456789\");" + } + ] + } + }, + "/api/v1/sessions/{session_id}/revoke": { + "post": { + "description": "Immediately invalidates a specific user session by session ID, setting its status to 'revoked'. Once revoked, the session cannot be used for any future API requests or application access. Use this endpoint to implement session-level logout, force a user to reauthenticate on a specific device, or terminate suspicious sessions. The revocation is instantaneous and irreversible. Returns the revoked session details including the session ID, user ID, and the revocation timestamp.", + "tags": [ + "Sessions" + ], + "summary": "Revoke user session", + "operationId": "SessionService_RevokeSession", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier for the session to revoke. Must start with 'ses_' prefix.", + "name": "session_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully revoked the session. Returns the revoked session details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/sessionsRevokeSessionResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.session.revokeSession(\"ses_123456789\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "res = scalekit_client.sessions.revoke_session(session_id=\"ses_123456789\")" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Session().RevokeSession(ctx, \"ses_123456789\")\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "RevokeSessionResponse res = scalekitClient.sessions().revokeSession(\"ses_123456789\");" + } + ] + } + }, + "/api/v1/users": { + "get": { + "description": "Retrieves a paginated list of all users across your entire environment. Use this endpoint to view all users regardless of their organization memberships. This is useful for administrative purposes, user audits, or when you need to see all users in your Scalekit environment. Supports pagination for large user bases.", + "tags": [ + "Users" + ], + "summary": "List all users in environment", + "operationId": "UserService_ListUsers", + "parameters": [ + { + "schema": { + "type": "integer", + "format": "int64" + }, + "description": "Maximum number of organizations to return per page. Must be between 10 and 100", + "name": "page_size", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Pagination token from the previous response. Use to retrieve the next page of organizations", + "name": "page_token", + "in": "query" + } + ], + "responses": { + "200": { + "description": "List of users.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/usersListUsersResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const response = await scalekit.user.listUsers(\n { pageSize: 100 });" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "# pass empty org to fetch all users in environment\nresp,_ = scalekit_client.users.list_users(organization_id=\"\", page_size=100)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "all, err := scalekitClient.User().ListUsers(ctx, &scalekit.ListUsersOptions{PageSize: 100})" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ListUsersRequest lur = ListUsersRequest.\n newBuilder().setPageSize(100).build();\nListUsersResponse allUsers = users.listUsers(lur);" + } + ] + } + }, + "/api/v1/users/{id}": { + "get": { + "description": "Retrieves all details for a user by system-generated user ID or external ID. The response includes organization memberships and user metadata.", + "tags": [ + "Users" + ], + "summary": "Get user", + "operationId": "UserService_GetUser", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "System-generated user ID", + "name": "id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Your application's unique identifier for this organization, used to link Scalekit with your system.", + "name": "external_id", + "in": "query" + } + ], + "responses": { + "200": { + "description": "User details retrieved successfully. Returns full user object with system-generated fields and timestamps.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/usersGetUserResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const { user } = await scalekit.user.getUser(\"usr_123456\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "resp = scalekit_client.users.get_user(user_id=\"usr_123456\")\nuser = resp.user" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.User().GetUser(ctx, \"usr_123456\")\nif err != nil {\n // handle error\n}\nuser := resp.User" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "GetUserResponse resp = scalekitClient.users().getUser(\"usr_123456\");\nUser user = resp.getUser();" + } + ] + }, + "delete": { + "description": "Permanently removes a user from your environment and deletes all associated data. Use this endpoint when you need to completely remove a user account. This action deletes the user's profile, memberships, and all related data across all organizations. This operation cannot be undone, so use with caution.", + "tags": [ + "Users" + ], + "summary": "Delete user permanently", + "operationId": "UserService_DeleteUser", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "System-generated user ID. Must start with 'usr_' (19-25 characters)", + "name": "id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "External system identifier from connected directories. Must match existing records", + "name": "external_id", + "in": "query" + } + ], + "responses": { + "200": { + "description": "User successfully deleted. No content returned", + "content": { + "application/json": { + "schema": {} + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.user.deleteUser(\"usr_123\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "scalekit_client.users.delete_user(organization_id=\"org_123\", \n user_id=\"usr_123\")" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "if err := scalekitClient.User().DeleteUser(ctx, \n \"usr_123\"); err != nil {\n panic(err)\n}" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "users.deleteUser(\"usr_123\");" + } + ] + }, + "patch": { + "description": "Modifies user account information including profile details, metadata, and external ID. Use this endpoint to update a user's personal information, contact details, or custom metadata. You can update the user's profile, phone number, and metadata fields. Note that fields like user ID, email address, environment ID, and creation time cannot be modified.", + "tags": [ + "Users" + ], + "summary": "Update user information", + "operationId": "UserService_UpdateUser", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "System-generated user ID. Must start with 'usr_' and be 19-25 characters long.", + "name": "id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "string" + }, + "description": "Your application's unique identifier for this organization, used to link Scalekit with your system.", + "name": "external_id", + "in": "query" + } + ], + "responses": { + "200": { + "description": "User updated successfully. Returns the modified user object with updated timestamps.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/usersUpdateUserResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "await scalekit.user.updateUser(\"usr_123\", {\n\tuserProfile: {\n\t\tfirstName: \"John\",\n\t\tlastName: \"Smith\",\n\t},\n\tmetadata: {\n\t\tdepartment: \"sales\",\n\t},\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "import os\nfrom scalekit import ScalekitClient\nfrom scalekit.v1.users.users_pb2 import UpdateUser\nfrom scalekit.v1.commons.commons_pb2 import UserProfile\nscalekit_client = ScalekitClient(\n env_url=os.getenv(\"SCALEKIT_ENV_URL\"),\n client_id=os.getenv(\"SCALEKIT_CLIENT_ID\"),\n client_secret=os.getenv(\"SCALEKIT_CLIENT_SECRET\"),\n)\nupdate_user = UpdateUser(\n user_profile=UserProfile(\n first_name=\"John\",\n last_name=\"Smith\"\n ),\n metadata={\"department\": \"sales\"}\n)\nscalekit_client.users.update_user(organization_id=\"org_123\", \n user=update_user)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "upd := &usersv1.UpdateUser{\n UserProfile: &usersv1.UpdateUserProfile{\n FirstName: \"John\",\n LastName: \"Smith\",\n },\n Metadata: map[string]string{\n \"department\": \"sales\",\n },\n}\nscalekitClient.User().UpdateUser(ctx, \"usr_123\", upd)" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "UpdateUser upd = UpdateUser.newBuilder()\n .setUserProfile(\n UpdateUserProfile.newBuilder()\n .setFirstName(\"John\")\n .setLastName(\"Smith\")\n .build())\n .putMetadata(\"department\", \"sales\")\n .build();\nUpdateUserRequest updReq = UpdateUserRequest.\n newBuilder().setUser(upd).build();\nusers.updateUser(\"usr_123\", updReq);" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "User fields to update. Only specified fields will be modified. Required fields must be provided if being changed.", + "$ref": "#/components/schemas/v1usersUpdateUser", + "examples": [ + { + "firstName": "John", + "lastName": "Doe" + } + ] + } + } + }, + "required": true + } + } + }, + "/api/v1/users/{user_id}/sessions": { + "get": { + "description": "Retrieves a paginated list of all sessions associated with a specific user across all devices and browsers. Use this endpoint to audit user activity, display all active sessions in account management interfaces, or verify user authentication status across devices. Supports filtering by session status (active, expired, revoked, logout) and time range (creation date). Returns session details for each session including device information, IP address, geolocation, and current status. The response includes pagination metadata (page tokens and total count) to handle large session lists efficiently.", + "tags": [ + "Sessions" + ], + "summary": "List user sessions", + "operationId": "SessionService_GetUserSessions", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier for the user whose sessions to retrieve. Must start with 'usr_' prefix.", + "name": "user_id", + "in": "path", + "required": true + }, + { + "schema": { + "type": "integer", + "format": "int64" + }, + "description": "Maximum number of sessions to return in a single page. Optional parameter. If not specified, defaults to a server-defined limit. Use smaller values for faster responses, larger values for fewer requests.", + "name": "page_size", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Pagination token from the previous response for retrieving the next page of results. Leave empty for the first page. Use the next_page_token from a previous response to fetch subsequent pages.", + "name": "page_token", + "in": "query" + }, + { + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "style": "form", + "explode": true, + "description": "Filter sessions by one or more status values. Possible values: 'active', 'expired', 'revoked', 'logout'. Leave empty to include all statuses. Multiple values use OR logic (e.g., status=['active', 'expired'] returns sessions that are either active OR expired).", + "name": "filter.status", + "in": "query" + }, + { + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Filter to include only sessions created on or after this timestamp. Optional. Uses RFC 3339 format. Useful for querying sessions within a specific time window.", + "name": "filter.start_time", + "in": "query" + }, + { + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Filter to include only sessions created on or before this timestamp. Optional. Uses RFC 3339 format. Must be after start_time if both are specified.", + "name": "filter.end_time", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved user sessions. Returns a list of sessions with pagination information", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/sessionsUserSessionDetails" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "// Basic usage\nconst res = await scalekit.session.getUserSessions(\"user_123\");\n\n// With pagination and filtering\nconst res = await scalekit.session.getUserSessions(\"user_123\", {\n pageSize: 10,\n pageToken: \"next_page_token\",\n filter: {\n status: [\"ACTIVE\"],\n startTime: new Date(\"2024-01-01\"),\n endTime: new Date(\"2024-12-31\")\n }\n});" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "# Basic usage\nres = scalekit_client.sessions.get_user_sessions(user_id=\"user_123\")\n\n# With pagination and filtering\nfrom google.protobuf.timestamp_pb2 import Timestamp\nfrom datetime import datetime\n\nstart_time = Timestamp()\nstart_time.FromDatetime(datetime(2024, 1, 1))\nend_time = Timestamp()\nend_time.FromDatetime(datetime(2024, 12, 31))\n\nfilter_obj = scalekit_client.sessions.create_session_filter(\n status=[\"ACTIVE\"], start_time=start_time, end_time=end_time\n)\nres = scalekit_client.sessions.get_user_sessions(\n user_id=\"user_123\", page_size=10, page_token=\"next_page_token\", filter=filter_obj\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "// Basic usage\nresp, err := scalekitClient.Session().GetUserSessions(ctx, \"user_123\", 0, \"\", nil)\nif err != nil { /* handle err */ }\n\n// With pagination and filtering\n// import \"time\", sessionsv1 \"...\", \"google.golang.org/protobuf/types/known/timestamppb\"\nstartTime, _ := time.Parse(time.RFC3339, \"2024-01-01T00:00:00Z\")\nendTime, _ := time.Parse(time.RFC3339, \"2024-12-31T23:59:59Z\")\nfilter := &sessionsv1.UserSessionFilter{\n Status: []string{\"ACTIVE\"},\n StartTime: timestamppb.New(startTime),\n EndTime: timestamppb.New(endTime),\n}\nresp, err := scalekitClient.Session().GetUserSessions(ctx, \"user_123\", 10, \"next_page_token\", filter)\nif err != nil { /* handle err */ }" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "// Basic usage\nUserSessionDetails res = scalekitClient.sessions().getUserSessions(\"user_123\", null, null, null);\n\n// With pagination and filtering\n// import UserSessionFilter, Timestamp, Instant\nUserSessionFilter filter = UserSessionFilter.newBuilder()\n .addStatus(\"ACTIVE\")\n .setStartTime(Timestamp.newBuilder().setSeconds(Instant.parse(\"2024-01-01T00:00:00Z\").getEpochSecond()).build())\n .setEndTime(Timestamp.newBuilder().setSeconds(Instant.parse(\"2024-12-31T23:59:59Z\").getEpochSecond()).build())\n .build();\nUserSessionDetails res = scalekitClient.sessions().getUserSessions(\"user_123\", 10, \"next_page_token\", filter);" + } + ] + } + }, + "/api/v1/users/{user_id}/sessions/revoke": { + "post": { + "description": "Immediately invalidates all active sessions for a specific user across all devices and browsers, setting their status to 'revoked'. Use this endpoint to implement global logout functionality, force re-authentication after security incidents, or terminate all sessions following a password reset or credential compromise. Only active sessions are revoked; already expired, logout, or previously revoked sessions remain unchanged. The revocation is atomic and instantaneous. Returns a list of all revoked sessions with their details and a total count of sessions revoked.", + "tags": [ + "Sessions" + ], + "summary": "Revoke all user sessions", + "operationId": "SessionService_RevokeAllUserSessions", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "Unique identifier for the user whose all sessions will be revoked. Must start with 'usr_' prefix.", + "name": "user_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Successfully revoked all user sessions. Returns the list of revoked sessions and total count", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/sessionsRevokeAllUserSessionsResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.session.revokeAllUserSessions(\"user_123\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "res = scalekit_client.sessions.revoke_all_user_sessions(user_id=\"user_123\")" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.Session().RevokeAllUserSessions(ctx, \"user_123\")\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "RevokeAllUserSessionsResponse res = scalekitClient.sessions().revokeAllUserSessions(\"user_123\");" + } + ] + } + }, + "/api/v1/users:search": { + "get": { + "description": "Searches for users across the entire environment by email address, user ID, or external ID. The query must be at least 3 characters and is case-insensitive. Returns a paginated list of matching users with up to 30 results per page. Use the next_page_token from the response to retrieve subsequent pages.", + "tags": [ + "Users" + ], + "summary": "Search users", + "operationId": "UserService_SearchUsers", + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 3, + "maxLength": 100 + }, + "description": "Search term to match against user email, IDs, or external IDs. Must be at least 3 characters. Case insensitive.", + "name": "query", + "in": "query", + "required": true + }, + { + "schema": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 30 + }, + "description": "Maximum number of users to return per page. Value must be between 1 and 30.", + "name": "page_size", + "in": "query" + }, + { + "schema": { + "type": "string" + }, + "description": "Token from a previous response for pagination. Provide this to retrieve the next page of results.", + "name": "page_token", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Matching users returned; includes pagination cursors for navigating large result sets.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/usersSearchUsersResponse" + } + } + } + }, + "400": { + "description": "Bad Request - query must be at least 3 characters and no more than 100 characters.", + "content": { + "application/json": { + "schema": {} + } + } + } + } + } + }, + "/api/v1/webauthn/credentials": { + "get": { + "description": "Retrieves all registered passkeys for the current user, including device information, creation timestamps, and display names. Use this to show users their registered authenticators.", + "tags": [ + "Passkeys" + ], + "summary": "List user's passkeys", + "operationId": "WebAuthnService_ListCredentials", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "User ID to list credentials for (optional, current user if not provided)", + "name": "user_id", + "in": "query" + } + ], + "responses": { + "200": { + "description": "List of passkeys with metadata", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/webauthnListCredentialsResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.webauthn.listCredentials(\"user_123\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "res = scalekit_client.webauthn.list_credentials(user_id=\"user_123\")" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.WebAuthn().ListCredentials(ctx, \"user_123\")\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "ListCredentialsResponse res = scalekitClient.webauthn().listCredentials(\"user_123\");" + } + ] + } + }, + "/api/v1/webauthn/credentials/{credential_id}": { + "delete": { + "description": "Deletes a specific passkey credential for the current user. After removal, the authenticator can no longer be used for authentication.", + "tags": [ + "Passkeys" + ], + "summary": "Remove a passkey", + "operationId": "WebAuthnService_DeleteCredential", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "The credential ID to delete", + "name": "credential_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Passkey successfully deleted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/webauthnDeleteCredentialResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.webauthn.deleteCredential(\"wac_123\");" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "res = scalekit_client.webauthn.delete_credential(credential_id=\"wac_123\")" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.WebAuthn().DeleteCredential(ctx, \"wac_123\")\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "DeleteCredentialResponse res = scalekitClient.webauthn().deleteCredential(\"wac_123\");" + } + ] + }, + "patch": { + "description": "Updates the display name of a passkey credential to help users identify their authenticators. Only the display name can be modified.", + "tags": [ + "Passkeys" + ], + "summary": "Rename a passkey", + "operationId": "WebAuthnService_UpdateCredential", + "parameters": [ + { + "schema": { + "type": "string" + }, + "description": "The credential ID to update", + "name": "credential_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Passkey successfully updated with new name", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/webauthnUpdateCredentialResponse" + } + } + } + } + }, + "x-codeSamples": [ + { + "label": "Node.js SDK", + "lang": "javascript", + "source": "const res = await scalekit.webauthn.updateCredential(\n \"wac_123\",\n \"Work Laptop Passkey\"\n);" + }, + { + "label": "Python SDK", + "lang": "python", + "source": "res = scalekit_client.webauthn.update_credential(\n credential_id=\"wac_123\",\n display_name=\"Work Laptop Passkey\"\n)" + }, + { + "label": "Go SDK", + "lang": "go", + "source": "resp, err := scalekitClient.WebAuthn().UpdateCredential(\n ctx,\n \"wac_123\",\n \"Work Laptop Passkey\",\n)\nif err != nil { /* handle err */ }\n_ = resp" + }, + { + "label": "Java SDK", + "lang": "java", + "source": "UpdateCredentialResponse res = scalekitClient.webauthn()\n .updateCredential(\"wac_123\", \"Work Laptop Passkey\");" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAuthnServiceUpdateCredentialBody" + } + } + }, + "required": true + } + } + } + }, + "webhooks": { + "organization.created": { + "post": { + "summary": "Organization Created", + "description": "Triggered when a new organization is created in Scalekit", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_1234567890", + "type": "organization.created", + "object": "Organization", + "occurred_at": "2024-01-15T10:30:00.123456789Z", + "environment_id": "env_1234567890", + "organization_id": "org_1234567890", + "data": { + "create_time": "2025-12-09T09:25:02.02Z", + "display_name": "AcmeCorp", + "external_id": "org_external_123", + "id": "org_1234567890", + "metadata": null, + "region_code": "US", + "update_time": "2025-12-09T09:25:02.025330364Z", + "settings": { + "features": [ + { + "enabled": true, + "name": "sso" + }, + { + "enabled": false, + "name": "dir_sync" + } + ] + } + }, + "display_name": "Organization Created" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "organization.updated": { + "post": { + "summary": "Organization Updated", + "description": "Triggered when an organization is updated", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_2345678901", + "type": "organization.updated", + "object": "Organization", + "occurred_at": "2024-01-15T10:35:00.123456789Z", + "environment_id": "env_1234567890", + "organization_id": "org_1234567890", + "data": { + "create_time": "2025-12-09T09:25:02.02Z", + "display_name": "AcmeCorp", + "external_id": "org_external_123", + "id": "org_1234567890", + "metadata": null, + "region_code": "US", + "update_time": "2025-12-09T09:25:02.025330364Z", + "settings": { + "features": [ + { + "enabled": true, + "name": "sso" + }, + { + "enabled": false, + "name": "dir_sync" + } + ] + } + }, + "display_name": "Organization Updated" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "organization.deleted": { + "post": { + "summary": "Organization Deleted", + "description": "Triggered when an organization is deleted", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_3456789012", + "type": "organization.deleted", + "object": "Organization", + "occurred_at": "2024-01-15T10:40:00.123456789Z", + "environment_id": "env_1234567890", + "organization_id": "org_1234567890", + "data": { + "create_time": "2025-12-09T09:25:02.02Z", + "deleted_at": "2025-12-09T10:25:45.337417Z", + "display_name": "AcmeCorp", + "external_id": "org_external_123", + "id": "org_1234567890", + "metadata": null, + "region_code": "US", + "update_time": "2025-12-09T09:25:02.025330364Z", + "settings": { + "features": [ + { + "enabled": true, + "name": "sso" + }, + { + "enabled": false, + "name": "dir_sync" + } + ] + } + }, + "display_name": "Organization Deleted" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "user.signup": { + "post": { + "summary": "User Signup", + "description": "Triggered when a user signs up to create a new organization", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_1234567890", + "type": "user.signup", + "object": "OrgMembership", + "occurred_at": "2024-01-15T10:30:00.123456789Z", + "environment_id": "env_1234567890", + "organization_id": "org_102690563312124938", + "data": { + "organization": { + "id": "org_102690563312124938", + "create_time": "2025-12-09T10:19:05.48Z", + "display_name": "", + "external_id": null, + "metadata": null, + "region_code": "US", + "update_time": "2025-12-09T12:04:41.386974738Z", + "settings": { + "features": [ + { + "enabled": true, + "name": "sso" + }, + { + "enabled": true, + "name": "dir_sync" + } + ] + } + }, + "user": { + "create_time": "2025-12-09T12:04:41.39Z", + "email": "amit.ash1996@gmail.com", + "external_id": "", + "id": "usr_102701193205121289", + "metadata": {}, + "update_time": "2025-12-09T12:04:41.391988278Z", + "user_profile": { + "custom_attributes": null, + "email_verified": true, + "external_identities": null, + "family_name": "doe", + "gender": "", + "given_name": "John", + "groups": null, + "id": "usp_102701193205186825", + "locale": "", + "metadata": {}, + "name": "John Doe", + "phone_number": "", + "phone_number_verified": false, + "picture": "https://lh3.googleusercontent.com/a/abcdef", + "preferred_username": "" + } + } + }, + "display_name": "User Signup" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "user.login": { + "post": { + "summary": "User Login", + "description": "Triggered when a user logs in and a session is created", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_102701193859432713", + "type": "user.login", + "object": "User", + "occurred_at": "2025-12-09T12:04:41.781873312Z", + "environment_id": "env_96736846679245078", + "organization_id": "org_102701193188409609", + "data": { + "user": { + "create_time": "2025-12-09T12:04:41.39Z", + "email": "john.doe@acmecorp.com", + "external_id": "ext_123456789", + "id": "usr_123456789", + "last_login_time": "2025-12-09T12:04:41.48Z", + "metadata": {}, + "update_time": "2025-12-09T12:04:41.391988Z", + "user_profile": { + "custom_attributes": null, + "email_verified": true, + "external_identities": [ + { + "connection_id": "conn_97896332307464201", + "connection_provider": "GOOGLE", + "connection_type": "OAUTH", + "connection_user_id": "105055379523565727691", + "created_time": "2025-12-09T12:04:41.47Z", + "is_social": true, + "last_login_time": "2025-12-09T12:04:41.469311Z", + "last_synced_time": "2025-12-09T12:04:41.469311Z" + } + ], + "family_name": "Doe", + "gender": "", + "given_name": "John", + "groups": null, + "id": "usp_102701193205186825", + "locale": "", + "metadata": {}, + "name": "John Doe", + "phone_number": "", + "phone_number_verified": false, + "picture": "https://lh3.googleusercontent.com/a/abcdef", + "preferred_username": "" + } + }, + "user_session": { + "absolute_expires_at": "2026-01-08T12:04:41.737394Z", + "authenticated_organizations": [ + "org_102701193188409609" + ], + "created_at": "2025-12-09T12:04:41.48Z", + "expired_at": null, + "idle_expires_at": "2025-12-16T12:04:41.737395Z", + "last_active_at": "2025-12-09T12:04:41.747206Z", + "logout_at": null, + "organization_id": "org_102701193188409609", + "session_id": "ses_102701193356116233", + "status": "ACTIVE", + "updated_at": "2025-12-09T12:04:41.748512Z", + "user_id": "usr_102701193205121289", + "device": { + "browser": "Chrome", + "browser_version": "142.0.0.0", + "device_type": "Desktop", + "ip": "152.59.144.211", + "location": { + "city": "Patna", + "latitude": "25.594095", + "longitude": "85.137564", + "region": "IN", + "region_subdivision": "INBR" + }, + "os": "macOS", + "os_version": "10.15.7", + "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36" + } + } + }, + "display_name": "User Login" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "user.logout": { + "post": { + "summary": "User Logout", + "description": "Triggered when a user's session is terminated", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_102708230123160586", + "type": "user.logout", + "object": "User", + "occurred_at": "2025-12-09T13:14:35.722070822Z", + "environment_id": "env_96736846679245078", + "organization_id": "org_102701193188409609", + "data": { + "user": { + "create_time": "2025-12-09T12:04:41.39Z", + "email": "john.doe@acmecorp.com", + "external_id": "ext_123456789", + "id": "usr_123456789", + "last_login_time": "2025-12-09T12:04:41.48Z", + "metadata": {}, + "update_time": "2025-12-09T12:04:41.391988Z", + "user_profile": { + "custom_attributes": null, + "email_verified": true, + "external_identities": [ + { + "connection_id": "conn_97896332307464201", + "connection_provider": "GOOGLE", + "connection_type": "OAUTH", + "connection_user_id": "105055379523565727691", + "created_time": "2025-12-09T12:04:41.47Z", + "is_social": true, + "last_login_time": "2025-12-09T12:04:41.469311Z", + "last_synced_time": "2025-12-09T12:04:41.469311Z" + } + ], + "family_name": "Doe", + "gender": "", + "given_name": "John", + "groups": null, + "id": "usp_102701193205186825", + "locale": "", + "metadata": {}, + "name": "John Doe", + "phone_number": "", + "phone_number_verified": false, + "picture": "https://lh3.googleusercontent.com/a/abcdef", + "preferred_username": "" + } + }, + "user_session": { + "absolute_expires_at": "2026-01-08T12:04:41.737394Z", + "authenticated_organizations": [ + "org_102701193188409609" + ], + "created_at": "2025-12-09T12:04:41.48Z", + "expired_at": null, + "idle_expires_at": "2025-12-16T12:04:41.737395Z", + "last_active_at": "2025-12-09T12:04:41.747206Z", + "logout_at": null, + "organization_id": "org_102701193188409609", + "session_id": "ses_102701193356116233", + "status": "ACTIVE", + "updated_at": "2025-12-09T12:04:41.748512Z", + "user_id": "usr_102701193205121289", + "device": { + "browser": "Chrome", + "browser_version": "142.0.0.0", + "device_type": "Desktop", + "ip": "152.59.144.211", + "location": { + "city": "Patna", + "latitude": "25.594095", + "longitude": "85.137564", + "region": "IN", + "region_subdivision": "INBR" + }, + "os": "macOS", + "os_version": "10.15.7", + "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36" + } + } + }, + "display_name": "User Logout" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "user.organization_invitation": { + "post": { + "summary": "User Organization Invitation", + "description": "Triggered when a user is invited to join an organization", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_4567890123", + "type": "user.organization_invitation", + "object": "OrgMembership", + "occurred_at": "2024-01-15T11:00:00.123456789Z", + "environment_id": "env_1234567890", + "organization_id": "org_102690563312124938", + "data": { + "organization": { + "id": "org_102690563312124938", + "create_time": "2025-12-09T10:19:05.48Z", + "display_name": "Acme Corp", + "external_id": "org_external_123", + "metadata": null, + "region_code": "US", + "update_time": "2025-12-09T12:04:41.386974738Z", + "settings": { + "features": [ + { + "enabled": true, + "name": "sso" + }, + { + "enabled": true, + "name": "dir_sync" + } + ] + } + }, + "user": { + "create_time": "2025-12-09T12:04:41.39Z", + "email": "john.doe@acmecorp.com", + "external_id": "ext_123456789", + "id": "usr_123456789", + "metadata": {}, + "update_time": "2025-12-09T12:04:41.391988Z", + "user_profile": { + "custom_attributes": null, + "email_verified": true, + "external_identities": [ + { + "connection_id": "conn_97896332307464201", + "connection_provider": "GOOGLE", + "connection_type": "OAUTH", + "connection_user_id": "105055379523565727691", + "created_time": "2025-12-09T12:04:41.47Z", + "is_social": true, + "last_login_time": "2025-12-09T12:04:41.469311Z", + "last_synced_time": "2025-12-09T12:04:41.469311Z" + } + ], + "family_name": "Doe", + "gender": "", + "given_name": "John", + "groups": null, + "id": "usp_102701193205186825", + "locale": "", + "metadata": {}, + "name": "John Doe", + "phone_number": "", + "phone_number_verified": false, + "picture": "https://lh3.googleusercontent.com/a/abcdef", + "preferred_username": "" + } + } + }, + "display_name": "User Organization Invitation" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "user.organization_membership_created": { + "post": { + "summary": "User Organization Membership Created", + "description": "Triggered when a user joins an organization", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_5678901234", + "type": "user.organization_membership_created", + "object": "OrgMembership", + "occurred_at": "2024-01-15T11:05:00.123456789Z", + "environment_id": "env_1234567890", + "organization_id": "org_102690563312124938", + "data": { + "organization": { + "id": "org_102690563312124938", + "create_time": "2025-12-09T10:19:05.48Z", + "display_name": "Acme Corp", + "external_id": "org_external_123", + "metadata": null, + "region_code": "US", + "update_time": "2025-12-09T12:04:41.386974738Z", + "settings": { + "features": [ + { + "enabled": true, + "name": "sso" + }, + { + "enabled": true, + "name": "dir_sync" + } + ] + } + }, + "user": { + "create_time": "2025-12-09T12:04:41.39Z", + "email": "john.doe@acmecorp.com", + "external_id": "ext_123456789", + "id": "usr_123456789", + "metadata": {}, + "update_time": "2025-12-09T12:04:41.391988Z", + "user_profile": { + "custom_attributes": null, + "email_verified": true, + "external_identities": [ + { + "connection_id": "conn_97896332307464201", + "connection_provider": "GOOGLE", + "connection_type": "OAUTH", + "connection_user_id": "105055379523565727691", + "created_time": "2025-12-09T12:04:41.47Z", + "is_social": true, + "last_login_time": "2025-12-09T12:04:41.469311Z", + "last_synced_time": "2025-12-09T12:04:41.469311Z" + } + ], + "family_name": "Doe", + "gender": "", + "given_name": "John", + "groups": null, + "id": "usp_102701193205186825", + "locale": "", + "metadata": {}, + "name": "John Doe", + "phone_number": "", + "phone_number_verified": false, + "picture": "https://lh3.googleusercontent.com/a/abcdef", + "preferred_username": "" + } + } + }, + "display_name": "User Organization Membership Created" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "user.organization_membership_deleted": { + "post": { + "summary": "User Organization Membership Deleted", + "description": "Triggered when a user's membership in an organization is removed or deleted", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_9012345678", + "type": "user.organization_membership_deleted", + "object": "OrgMembership", + "occurred_at": "2024-01-15T11:10:00.123456789Z", + "environment_id": "env_1234567890", + "organization_id": "org_102690563312124938", + "data": { + "organization": { + "id": "org_102690563312124938", + "create_time": "2025-12-09T10:19:05.48Z", + "display_name": "Acme Corp", + "external_id": "org_external_123", + "metadata": null, + "region_code": "US", + "update_time": "2025-12-09T12:04:41.386974738Z", + "settings": { + "features": [ + { + "enabled": true, + "name": "sso" + }, + { + "enabled": true, + "name": "dir_sync" + } + ] + } + }, + "user": { + "create_time": "2025-12-09T12:04:41.39Z", + "email": "john.doe@acmecorp.com", + "external_id": "ext_123456789", + "id": "usr_123456789", + "metadata": {}, + "update_time": "2025-12-09T12:04:41.391988Z", + "user_profile": { + "custom_attributes": null, + "email_verified": true, + "external_identities": [ + { + "connection_id": "conn_97896332307464201", + "connection_provider": "GOOGLE", + "connection_type": "OAUTH", + "connection_user_id": "105055379523565727691", + "created_time": "2025-12-09T12:04:41.47Z", + "is_social": true, + "last_login_time": "2025-12-09T12:04:41.469311Z", + "last_synced_time": "2025-12-09T12:04:41.469311Z", + "raw_attributes": "{}", + "updated_time": "2025-12-09T12:04:41.473087Z" + } + ], + "family_name": "Doe", + "gender": "", + "given_name": "John", + "locale": "", + "metadata": {}, + "name": "John Doe", + "phone_number": "", + "phone_number_verified": false, + "picture": "https://lh3.googleusercontent.com/a/abcdef", + "preferred_username": "" + } + } + }, + "display_name": "User Organization Membership Deleted" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "user.organization_membership_updated": { + "post": { + "summary": "User Organization Membership Updated", + "description": "Triggered when a user's organization membership is updated, e.g., change of user's role in an organization", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_6789012345", + "type": "user.organization_membership_updated", + "object": "OrgMembership", + "occurred_at": "2024-01-15T11:10:00.123456789Z", + "environment_id": "env_1234567890", + "organization_id": "org_102690563312124938", + "data": { + "organization": { + "id": "org_102690563312124938", + "create_time": "2025-12-09T10:19:05.48Z", + "display_name": "Acme Corp", + "external_id": "org_external_123", + "metadata": null, + "region_code": "US", + "update_time": "2025-12-09T12:04:41.386974738Z", + "settings": { + "features": [ + { + "enabled": true, + "name": "sso" + }, + { + "enabled": true, + "name": "dir_sync" + } + ] + } + }, + "user": { + "create_time": "2025-12-09T12:04:41.39Z", + "email": "john.doe@acmecorp.com", + "external_id": "ext_123456789", + "id": "usr_123456789", + "metadata": {}, + "update_time": "2025-12-09T12:04:41.391988Z", + "user_profile": { + "custom_attributes": null, + "email_verified": true, + "external_identities": [ + { + "connection_id": "conn_97896332307464201", + "connection_provider": "GOOGLE", + "connection_type": "OAUTH", + "connection_user_id": "105055379523565727691", + "created_time": "2025-12-09T12:04:41.47Z", + "is_social": true, + "last_login_time": "2025-12-09T12:04:41.469311Z", + "last_synced_time": "2025-12-09T12:04:41.469311Z", + "raw_attributes": "{}", + "updated_time": "2025-12-09T12:04:41.473087Z" + } + ], + "family_name": "Doe", + "gender": "", + "given_name": "John", + "locale": "", + "metadata": {}, + "name": "John Doe", + "phone_number": "", + "phone_number_verified": false, + "picture": "https://lh3.googleusercontent.com/a/abcdef", + "preferred_username": "" + } + } + }, + "display_name": "User Organization Membership Updated" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "organization.directory_enabled": { + "post": { + "summary": "Directory Enabled", + "description": "Triggered when a directory sync is enabled", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_55136848686613000", + "type": "organization.directory_enabled", + "object": "Directory", + "occurred_at": "2025-01-15T08:55:22.802860294Z", + "environment_id": "env_27758032200925221", + "organization_id": "org_55135410258444802", + "data": { + "directory_type": "SCIM", + "enabled": true, + "id": "dir_55135622825771522", + "organization_id": "org_55135410258444802", + "provider": "OKTA", + "updated_at": "2025-01-15T08:55:22.792993454Z" + }, + "display_name": "Directory Enabled" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "organization.directory_disabled": { + "post": { + "summary": "Directory Disabled", + "description": "Triggered when a directory sync is disabled", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_53891640779079756", + "type": "organization.directory_disabled", + "object": "Directory", + "occurred_at": "2025-01-06T18:45:21.057814Z", + "environment_id": "env_53814739859406915", + "organization_id": "org_53879494091473415", + "data": { + "directory_type": "SCIM", + "enabled": false, + "id": "dir_53879621145330183", + "organization_id": "org_53879494091473415", + "provider": "OKTA", + "updated_at": "2025-01-06T18:45:21.04978184Z" + }, + "display_name": "Directory Disabled" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "organization.directory.user_created": { + "post": { + "summary": "Directory User Created", + "description": "Triggered when a new directory user is created", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_53891546994442316", + "type": "organization.directory.user_created", + "object": "DirectoryUser", + "occurred_at": "2025-01-06T18:44:25.153954Z", + "environment_id": "env_53814739859406915", + "organization_id": "org_53879494091473415", + "data": { + "active": true, + "cost_center": "QAUZJUHSTYCN", + "custom_attributes": { + "mobile_phone_number": "1-579-4072" + }, + "department": "HNXJPGISMIFN", + "division": "MJFUEYJOKICN", + "dp_id": "", + "email": "flavio@runolfsdottir.co.duk", + "employee_id": "AWNEDTILGaIZN", + "family_name": "Jaquelin", + "given_name": "Dayton", + "groups": [ + { + "id": "dirgroup_12312312312312", + "name": "Group Name" + } + ], + "id": "diruser_53891546960887884", + "language": "se", + "locale": "LLWLEWESPLDC", + "name": "QDRGUZZDYMFU", + "nickname": "DTUODYKGFPPC", + "organization": "AUIITQVUQGVH", + "organization_id": "org_53879494091473415", + "phone_number": "1-579-4072", + "preferred_username": "kuntala1233a", + "profile": "YMIUQUHKGVAX", + "raw_attributes": {}, + "title": "FKQBHCWJXZSC", + "user_type": "RBQFJSQEFAEH", + "zoneinfo": "America/Araguaina", + "roles": [ + { + "role_name": "billing_admin" + } + ] + }, + "display_name": "Directory User Created" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "organization.directory.user_updated": { + "post": { + "summary": "Directory User Updated", + "description": "Triggered when a directory user is updated", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_53891546994442317", + "type": "organization.directory.user_updated", + "object": "DirectoryUser", + "occurred_at": "2025-01-06T18:44:25.153954Z", + "environment_id": "env_53814739859406915", + "organization_id": "org_53879494091473415", + "data": { + "id": "diruser_12312312312312", + "organization_id": "org_53879494091473415", + "dp_id": "", + "preferred_username": "", + "email": "john.doe@example.com", + "active": true, + "name": "John Doe", + "roles": [ + { + "role_name": "billing_admin" + } + ], + "groups": [ + { + "id": "dirgroup_12312312312312", + "name": "Group Name" + } + ], + "given_name": "John", + "family_name": "Doe", + "nickname": "Jhonny boy", + "picture": "https://image.com/profile.jpg", + "phone_number": "1234567892", + "address": { + "postal_code": "64112", + "state": "Missouri", + "formatted": "123, Oxford Lane, Kansas City, Missouri, 64112" + }, + "custom_attributes": { + "attribute1": "value1", + "attribute2": "value2" + }, + "raw_attributes": {} + }, + "display_name": "Directory User Updated" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "organization.directory.user_deleted": { + "post": { + "summary": "Directory User Deleted", + "description": "Triggered when a directory user is deleted", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_53891546994442318", + "type": "organization.directory.user_deleted", + "object": "DirectoryUser", + "occurred_at": "2025-01-06T18:44:25.153954Z", + "environment_id": "env_53814739859406915", + "organization_id": "org_53879494091473415", + "data": { + "id": "diruser_12312312312312", + "organization_id": "org_12312312312312", + "dp_id": "", + "email": "john.doe@example.com" + }, + "display_name": "Directory User Deleted" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "organization.directory.group_created": { + "post": { + "summary": "Directory Group Created", + "description": "Triggered when a new directory group is created", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_38862741515010639", + "type": "organization.directory.group_created", + "object": "DirectoryGroup", + "occurred_at": "2024-09-25T02:26:39.036398577Z", + "environment_id": "env_32080745237316098", + "organization_id": "org_38609339635728478", + "data": { + "directory_id": "dir_38610496391217780", + "display_name": "Avengers", + "external_id": null, + "id": "dirgroup_38862741498233423", + "organization_id": "org_38609339635728478", + "raw_attributes": {} + }, + "display_name": "Directory Group Created" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "organization.directory.group_updated": { + "post": { + "summary": "Directory Group Updated", + "description": "Triggered when a directory group is updated", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_38864948910162368", + "type": "organization.directory.group_updated", + "object": "DirectoryGroup", + "occurred_at": "2024-09-25T02:48:34.745030921Z", + "environment_id": "env_32080745237316098", + "organization_id": "org_38609339635728478", + "data": { + "directory_id": "dir_38610496391217780", + "display_name": "Avengers", + "external_id": "", + "id": "dirgroup_38862741498233423", + "organization_id": "org_38609339635728478", + "raw_attributes": {} + }, + "display_name": "Directory Group Updated" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "organization.directory.group_deleted": { + "post": { + "summary": "Directory Group Deleted", + "description": "Triggered when a directory group is deleted", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_40650399597723966", + "type": "organization.directory.group_deleted", + "object": "DirectoryGroup", + "occurred_at": "2024-10-07T10:25:26.289331747Z", + "environment_id": "env_12205603854221623", + "organization_id": "org_39802449573184223", + "data": { + "directory_id": "dir_39802485862301855", + "display_name": "Admins", + "dp_id": "7c66a173-79c6-4270-ac78-8f35a8121e0a", + "id": "dirgroup_40072007005503806", + "organization_id": "org_39802449573184223", + "raw_attributes": {} + }, + "display_name": "Directory Group Deleted" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "organization.sso_created": { + "post": { + "summary": "SSO Connection Created", + "description": "Triggered when a new SSO connection is created for an organization", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_94567862441607493", + "type": "organization.sso_created", + "object": "Connection", + "environment_id": "env_74418471961625391", + "occurred_at": "2025-10-14T09:27:18.488720586Z", + "organization_id": "org_83544995172188677", + "data": { + "id": "conn_94567862424830277", + "organization_id": "org_83544995172188677", + "connection_type": "OIDC", + "provider": "OKTA" + }, + "display_name": "SSO Connection Created" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "organization.sso_enabled": { + "post": { + "summary": "SSO Connection Enabled", + "description": "Triggered when an SSO connection is enabled for an organization", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_94568078213382471", + "type": "organization.sso_enabled", + "object": "Connection", + "environment_id": "env_74418471961625391", + "occurred_at": "2025-10-14T09:29:27.098914861Z", + "organization_id": "org_83544995172188677", + "data": { + "id": "conn_94567862424830277", + "organization_id": "org_83544995172188677", + "connection_type": "OIDC", + "provider": "OKTA", + "enabled": true, + "status": "COMPLETED" + }, + "display_name": "SSO Connection Enabled" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "organization.sso_disabled": { + "post": { + "summary": "SSO Connection Disabled", + "description": "Triggered when an SSO connection is disabled for an organization", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_94557976165089560", + "type": "organization.sso_disabled", + "object": "Connection", + "environment_id": "env_74418471961625391", + "occurred_at": "2025-10-14T07:49:05.809554456Z", + "organization_id": "org_83544995172188677", + "data": { + "id": "conn_83545002856153607", + "organization_id": "org_83544995172188677", + "connection_type": "OIDC", + "provider": "OKTA", + "enabled": false, + "status": "COMPLETED" + }, + "display_name": "SSO Connection Disabled" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "organization.sso_deleted": { + "post": { + "summary": "SSO Connection Deleted", + "description": "Triggered when an SSO connection is deleted for an organization", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_94557997639926040", + "type": "organization.sso_deleted", + "object": "Connection", + "environment_id": "env_74418471961625391", + "occurred_at": "2025-10-14T07:49:18.604546332Z", + "organization_id": "org_83544995172188677", + "data": { + "id": "conn_83545002856153607", + "organization_id": "org_83544995172188677", + "connection_type": "OIDC", + "provider": "OKTA" + }, + "display_name": "SSO Connection Deleted" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "role.created": { + "post": { + "summary": "Role Created", + "description": "Triggered when a new role is created", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_1234567890", + "type": "role.created", + "object": "Role", + "occurred_at": "2024-01-15T10:30:00.123456789Z", + "environment_id": "env_1234567890", + "data": { + "description": "Viewer role with read-only access", + "display_name": "Viewer", + "extends": "member", + "id": "role_1234567890", + "name": "viewer" + }, + "display_name": "Role Created" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "role.updated": { + "post": { + "summary": "Role Updated", + "description": "Triggered when a role is updated", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_2345678901", + "type": "role.updated", + "object": "Role", + "occurred_at": "2024-01-15T10:35:00.123456789Z", + "environment_id": "env_1234567890", + "data": { + "description": "Updated viewer role with limited permissions", + "display_name": "Viewer", + "extends": "member", + "id": "role_1234567890", + "name": "viewer" + }, + "display_name": "Role Updated" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "role.deleted": { + "post": { + "summary": "Role Deleted", + "description": "Triggered when a role is deleted", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_3456789012", + "type": "role.deleted", + "object": "Role", + "occurred_at": "2024-01-15T10:40:00.123456789Z", + "environment_id": "env_1234567890", + "data": { + "description": "Updated viewer role with limited permissions", + "display_name": "Viewer", + "extends": "member", + "id": "role_1234567890", + "name": "viewer" + }, + "display_name": "Role Deleted" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "permission.created": { + "post": { + "summary": "Permission Created", + "description": "Triggered when a new permission is created", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_1234567890", + "type": "permission.created", + "object": "Permission", + "occurred_at": "2024-01-15T10:30:00.123456789Z", + "environment_id": "env_1234567890", + "data": { + "description": "Permission to manage data", + "id": "perm_1234567890", + "name": "data:manage" + }, + "display_name": "Permission Created" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "permission.updated": { + "post": { + "summary": "Permission Updated", + "description": "Triggered when a permission is updated", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_2345678901", + "type": "permission.updated", + "object": "Permission", + "occurred_at": "2024-01-15T10:35:00.123456789Z", + "environment_id": "env_1234567890", + "data": { + "description": "Updated permission to manage all data", + "id": "perm_1234567890", + "name": "data:manage" + }, + "display_name": "Permission Updated" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + }, + "permission.deleted": { + "post": { + "summary": "Permission Deleted", + "description": "Triggered when a permission is deleted", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScalekitEvent" + }, + "example": { + "spec_version": "1", + "id": "evt_3456789012", + "type": "permission.deleted", + "object": "Permission", + "occurred_at": "2024-01-15T10:40:00.123456789Z", + "environment_id": "env_1234567890", + "data": { + "description": "Updated permission to manage all data", + "id": "perm_1234567890", + "name": "data:manage" + }, + "display_name": "Permission Deleted" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook received successfully" + } + } + } + } + }, + "components": { + "securitySchemes": { + "oauth2": { + "type": "oauth2", + "flows": { + "clientCredentials": { + "tokenUrl": "https://$SCALEKIT_ENVIRONMENT_URL/oauth/token", + "scopes": { + "": "No scope required for client credentials flow" + } + } + } + } + }, + "schemas": { + "connectionsConnectionProvider": { + "type": "string", + "enum": [ + "OKTA", + "GOOGLE", + "MICROSOFT_AD", + "AUTH0", + "ONELOGIN", + "PING_IDENTITY", + "JUMPCLOUD", + "CUSTOM", + "GITHUB", + "GITLAB", + "LINKEDIN", + "SALESFORCE", + "MICROSOFT", + "IDP_SIMULATOR", + "SCALEKIT", + "ADFS" + ] + }, + "connectionsConnectionStatus": { + "type": "string", + "enum": [ + "DRAFT", + "IN_PROGRESS", + "COMPLETED" + ] + }, + "connectionsConnectionType": { + "type": "string", + "enum": [ + "OIDC", + "SAML", + "PASSWORD", + "OAUTH", + "PASSWORDLESS", + "BASIC", + "BEARER", + "API_KEY", + "WEBAUTHN" + ] + }, + "connectionsListConnection": { + "type": "object", + "properties": { + "domains": { + "description": "List of domains configured with this connection", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "yourapp.com", + "yourworkspace.com" + ] + ] + }, + "enabled": { + "description": "Whether the connection is currently active for organization users", + "type": "boolean", + "examples": [ + false + ] + }, + "id": { + "description": "Unique identifier of the connection", + "type": "string", + "examples": [ + "conn_2123312131125533" + ] + }, + "key_id": { + "description": "Alternative identifier for this connection, typically used in frontend applications or URLs", + "type": "string", + "examples": [ + "conn_2123312131125533" + ] + }, + "organization_id": { + "description": "Unique identifier of the organization that owns this connection", + "type": "string", + "examples": [ + "org_2123312131125533" + ] + }, + "organization_name": { + "description": "Name of the organization of the connection", + "type": "string", + "examples": [ + "Your Organization" + ] + }, + "provider": { + "description": "Identity provider type (e.g., OKTA, Google, Azure AD)", + "$ref": "#/components/schemas/connectionsConnectionProvider", + "examples": [ + "CUSTOM" + ] + }, + "provider_key": { + "description": "Key ID of the identity provider service that handles authentication", + "type": "string", + "examples": [ + "google" + ] + }, + "status": { + "description": "Current configuration status of the connection", + "$ref": "#/components/schemas/connectionsConnectionStatus", + "readOnly": true, + "examples": [ + "IN_PROGRESS" + ] + }, + "type": { + "description": "Authentication protocol used by the connection", + "$ref": "#/components/schemas/connectionsConnectionType", + "examples": [ + "OIDC" + ] + } + } + }, + "connectionsListConnectionsResponse": { + "type": "object", + "properties": { + "connections": { + "description": "List of connections matching the request criteria", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/connectionsListConnection" + } + } + } + }, + "UserServiceResendInviteBody": { + "type": "object" + }, + "usersInvite": { + "type": "object", + "properties": { + "created_at": { + "description": "Timestamp when the invite was originally created.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-07-10T08:00:00Z" + ] + }, + "expires_at": { + "description": "The time at which the invite expires.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-12-31T23:59:59Z" + ] + }, + "inviter_email": { + "description": "Identifier of the user or system that initiated the invite.", + "type": "string", + "examples": [ + "admin@example.com" + ] + }, + "organization_id": { + "description": "The organization to which the invite belongs.", + "type": "string", + "examples": [ + "org_987654321" + ] + }, + "resent_at": { + "description": "Timestamp when the invite was last resent, if applicable.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-07-15T09:30:00Z" + ] + }, + "resent_count": { + "description": "Number of times the invite has been resent.", + "type": "integer", + "format": "int32", + "examples": [ + 2 + ] + }, + "status": { + "description": "Current status of the invite (e.g., pending, accepted, expired, revoked).", + "type": "string", + "examples": [ + "pending_invite" + ] + }, + "user_id": { + "description": "User ID to whom the invite is sent. May be empty if the user has not signed up yet.", + "type": "string", + "examples": [ + "usr_123456" + ] + } + } + }, + "usersResendInviteResponse": { + "type": "object", + "properties": { + "invite": { + "description": "Updated invitation object containing the resent invitation details, including new expiration time and incremented resend counter.", + "$ref": "#/components/schemas/usersInvite", + "examples": [ + { + "expires_at": "2025-12-31T23:59:59Z", + "organization_id": "org_123", + "resent_count": 2, + "status": "pending_invite", + "user_id": "usr_456" + } + ] + } + } + }, + "errdetailsDebugInfo": { + "description": "Describes additional debugging info.", + "type": "object", + "properties": { + "detail": { + "description": "Additional debugging information provided by the server.", + "type": "string" + }, + "stack_entries": { + "description": "The stack trace entries indicating where the error occurred.", + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "HelpInfoLink": { + "description": "A documentation or reference link.", + "type": "object", + "properties": { + "description": { + "description": "Human-readable label for the link (e.g. \"User verification flow\").", + "type": "string" + }, + "url": { + "description": "Absolute URL to the documentation page (e.g. \"https://docs.scalekit.com/...\").", + "type": "string" + } + } + }, + "errdetailsHelpInfo": { + "description": "HelpInfo provides documentation links attached to an error response.\nWhen present in ErrorInfo, clients should surface these links to help\ndevelopers resolve the error. For example, a missing required field error\nmay include a link to the relevant guide.", + "type": "object", + "properties": { + "links": { + "description": "One or more links relevant to resolving the error.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/HelpInfoLink" + } + } + } + }, + "errdetailsLocalizedMessageInfo": { + "type": "object", + "properties": { + "locale": { + "type": "string" + }, + "message": { + "type": "string" + } + } + }, + "errdetailsRequestInfo": { + "description": "Contains metadata about the request that clients can attach when filing a bug\nor providing other forms of feedback.", + "type": "object", + "properties": { + "request_id": { + "description": "An opaque string that should only be interpreted by the service generating\nit. For example, it can be used to identify requests in the service's logs.", + "type": "string" + }, + "serving_data": { + "description": "Any data that was used to serve this request. For example, an encrypted\nstack trace that can be sent back to the service provider for debugging.", + "type": "string" + } + } + }, + "errdetailsResourceInfo": { + "description": "Describes the resource that is being accessed.", + "type": "object", + "properties": { + "description": { + "description": "Describes what error is encountered when accessing this resource.\nFor example, updating a cloud project may require the `writer` permission\non the developer console project.", + "type": "string" + }, + "owner": { + "type": "string" + }, + "required_permissions": { + "description": "The required permissions needed to access the resource.", + "type": "array", + "items": { + "type": "string" + } + }, + "resource_name": { + "type": "string" + }, + "user": { + "type": "string" + } + } + }, + "errdetailsToolErrorInfo": { + "type": "object", + "properties": { + "execution_id": { + "type": "string" + }, + "tool_error_code": { + "type": "string" + }, + "tool_error_message": { + "type": "string" + } + } + }, + "ValidationErrorInfoFieldViolation": { + "description": "A message type used to describe a single bad request field.", + "type": "object", + "properties": { + "constraint": { + "type": "string" + }, + "description": { + "description": "A description of why the request element is bad.", + "type": "string" + }, + "field": { + "type": "string" + } + } + }, + "errdetailsValidationErrorInfo": { + "description": "Describes violations in a client request. This error type focuses on the\nsyntactic aspects of the request.", + "type": "object", + "properties": { + "field_violations": { + "description": "Describes all violations in a client request.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/ValidationErrorInfoFieldViolation" + } + } + } + }, + "errdetailsErrorInfo": { + "type": "object", + "properties": { + "debug_info": { + "$ref": "#/components/schemas/errdetailsDebugInfo" + }, + "error_code": { + "type": "string" + }, + "help_info": { + "$ref": "#/components/schemas/errdetailsHelpInfo" + }, + "localized_message_info": { + "$ref": "#/components/schemas/errdetailsLocalizedMessageInfo" + }, + "request_info": { + "$ref": "#/components/schemas/errdetailsRequestInfo" + }, + "resource_info": { + "$ref": "#/components/schemas/errdetailsResourceInfo" + }, + "tool_error_info": { + "$ref": "#/components/schemas/errdetailsToolErrorInfo" + }, + "validation_error_info": { + "$ref": "#/components/schemas/errdetailsValidationErrorInfo" + } + } + }, + "commonsRole": { + "type": "object", + "properties": { + "display_name": { + "description": "Human-readable name for the role", + "type": "string", + "examples": [ + "Dev Team" + ] + }, + "id": { + "description": "Role ID", + "type": "string", + "readOnly": true, + "examples": [ + "role_79643236410327240" + ] + }, + "name": { + "description": "Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions.", + "type": "string", + "examples": [ + "team_dev" + ] + } + } + }, + "v1usersCreateMembership": { + "type": "object", + "properties": { + "inviter_email": { + "description": "Email address of the user who invited this member. Must be a valid email address.", + "type": "string", + "examples": [ + "john.doe@example.com" + ] + }, + "metadata": { + "description": "Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars).", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "examples": [ + { + "department": "engineering", + "location": "nyc-office" + } + ] + }, + "roles": { + "description": "Role to assign to the user within the organization", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/commonsRole" + }, + "examples": [ + [ + { + "name": "admin" + } + ] + ] + } + } + }, + "commonsMembershipStatus": { + "type": "string", + "enum": [ + "ACTIVE", + "INACTIVE", + "PENDING_INVITE", + "INVITE_EXPIRED" + ] + }, + "commonsOrganizationMembership": { + "type": "object", + "properties": { + "accepted_at": { + "description": "Timestamp when the user accepted the invitation.", + "type": "string", + "format": "date-time" + }, + "created_at": { + "description": "Timestamp when the invitation was created.", + "type": "string", + "format": "date-time" + }, + "display_name": { + "description": "Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes.", + "type": "string", + "examples": [ + "Acme Corporation" + ] + }, + "expires_at": { + "description": "Timestamp when the invitation expired.", + "type": "string", + "format": "date-time" + }, + "inviter_email": { + "description": "ID of the user who invited this user.", + "type": "string" + }, + "join_time": { + "description": "Timestamp when the membership was created. Automatically set by the server.", + "type": "string", + "format": "date-time" + }, + "membership_status": { + "$ref": "#/components/schemas/commonsMembershipStatus" + }, + "metadata": { + "description": "Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars).", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "examples": [ + { + "department": "engineering", + "location": "nyc-office" + } + ] + }, + "name": { + "description": "Organization name. This field stores the formal organization name used for identification and display purposes.", + "type": "string", + "examples": [ + "AcmeCorp" + ] + }, + "organization_id": { + "description": "Unique identifier for the organization. Immutable and read-only.", + "type": "string", + "examples": [ + "org_1234abcd5678efgh" + ] + }, + "permissions": { + "description": "Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform.", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "read_projects", + "write_tasks", + "manage_users" + ] + ] + }, + "provisioning_method": { + "description": "How the user was provisioned. \nPossible values: \n- `jit_using_sso` (Just-in-time provisioning during SSO login)\n- `allowed_email_domain` (User joined via allowed email domain matching)\n- `org_creator` (User created the organization)\n- `direct_provision` (User was directly provisioned via API or SCIM)\n- `invitation` (User was invited and accepted an invitation)", + "type": "string" + }, + "roles": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/commonsRole" + } + } + } + }, + "commonsIdentityProviderType": { + "type": "string", + "enum": [ + "OKTA", + "GOOGLE", + "MICROSOFT_AD", + "AUTH0", + "ONELOGIN", + "PING_IDENTITY", + "JUMPCLOUD", + "CUSTOM", + "GITHUB", + "GITLAB", + "LINKEDIN", + "SALESFORCE", + "MICROSOFT", + "IDP_SIMULATOR", + "SCALEKIT", + "ADFS" + ] + }, + "commonsExternalIdentity": { + "type": "object", + "properties": { + "connection_id": { + "description": "Unique identifier for the external identity connection. Immutable and read-only.", + "type": "string", + "readOnly": true, + "examples": [ + "conn_1234abcd5678efgh" + ] + }, + "connection_provider": { + "description": "Type of the identity provider.", + "$ref": "#/components/schemas/commonsIdentityProviderType", + "readOnly": true, + "examples": [ + "GOOGLE" + ] + }, + "connection_type": { + "description": "Name of the external identity connection.", + "type": "string", + "readOnly": true, + "examples": [ + "OAUTH" + ] + }, + "connection_user_id": { + "description": "Unique identifier for the user in the external identity provider system. Immutable and read-only.", + "type": "string", + "readOnly": true, + "examples": [ + "ext_user_12345" + ] + }, + "created_time": { + "description": "Timestamp when this external identity connection was first created. Immutable and read-only.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "is_social": { + "description": "Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only.", + "type": "boolean", + "readOnly": true, + "examples": [ + true + ] + }, + "last_login_time": { + "description": "Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "last_synced_time": { + "description": "Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system.", + "type": "string", + "format": "date-time", + "readOnly": true + } + } + }, + "commonsUserProfile": { + "type": "object", + "properties": { + "custom_attributes": { + "description": "Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs.", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "examples": [ + { + "department": "engineering", + "security_clearance": "level2" + } + ] + }, + "email_verified": { + "description": "Indicates if the user's email address has been verified. Automatically updated by the system.", + "type": "boolean", + "readOnly": true, + "examples": [ + true + ] + }, + "external_identities": { + "description": "List of external identity connections associated with the user profile.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/commonsExternalIdentity" + }, + "readOnly": true + }, + "family_name": { + "description": "The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed.", + "type": "string", + "examples": [ + "Doe" + ] + }, + "gender": { + "description": "The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations.", + "type": "string", + "examples": [ + "male" + ] + }, + "given_name": { + "description": "The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed.", + "type": "string", + "examples": [ + "John" + ] + }, + "groups": { + "description": "The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with.", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "admin", + "developer" + ] + ] + }, + "id": { + "description": "Unique system-generated identifier for the user profile. Immutable and read-only.", + "type": "string", + "readOnly": true, + "examples": [ + "usr_profile_1234abcd5678efgh" + ] + }, + "locale": { + "description": "The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include `en-US`, `en-GB`, `fr-FR`, `de-DE`, and `es-ES`.", + "type": "string", + "examples": [ + "en-US" + ] + }, + "metadata": { + "description": "Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs.", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "examples": [ + { + "department": "engineering", + "employee_type": "full-time", + "idp_user_id": "12345" + } + ] + }, + "name": { + "description": "The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given_name and family_name fields.", + "type": "string", + "examples": [ + "John Michael Doe" + ] + }, + "phone_number": { + "description": "The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., `+1` for US numbers). This field is optional.", + "type": "string", + "examples": [ + "+14155552671" + ] + }, + "phone_number_verified": { + "description": "Indicates if the user's phone number has been verified. Automatically updated by the system.", + "type": "boolean", + "readOnly": true, + "examples": [ + true + ] + }, + "picture": { + "description": "The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform.", + "type": "string", + "examples": [ + "https://example.com/avatar.jpg" + ] + }, + "preferred_username": { + "description": "The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed.", + "type": "string", + "examples": [ + "johndoe" + ] + } + } + }, + "usersUser": { + "type": "object", + "properties": { + "create_time": { + "description": "Timestamp when the user account was initially created. Automatically set by the server.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "email": { + "description": "Primary email address for the user. Must be unique across the environment and valid per RFC 5322.", + "type": "string", + "examples": [ + "user@example.com" + ] + }, + "external_id": { + "description": "Your application's unique identifier for this organization, used to link Scalekit with your system.", + "type": "string", + "examples": [ + "ext_12345a67b89c" + ] + }, + "id": { + "description": "Unique system-generated identifier for the user. Immutable once created.", + "type": "string", + "examples": [ + "usr_1234abcd5678efgh" + ] + }, + "last_login_time": { + "description": "Timestamp of the user's most recent successful authentication. Updated automatically.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "memberships": { + "description": "List of organization memberships. Automatically populated based on group assignments.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/commonsOrganizationMembership" + } + }, + "metadata": { + "description": "Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars).", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "examples": [ + { + "department": "engineering", + "location": "nyc-office" + } + ] + }, + "update_time": { + "description": "Timestamp of the last modification to the user account. Automatically updated by the server.", + "type": "string", + "format": "date-time", + "readOnly": true + }, + "user_profile": { + "description": "User's personal information including name, address, and other profile attributes.", + "$ref": "#/components/schemas/commonsUserProfile" + } + } + }, + "usersCreateMembershipResponse": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/usersUser" + } + } + }, + "v1usersUpdateMembership": { + "type": "object", + "properties": { + "metadata": { + "description": "Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars).", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "examples": [ + { + "department": "engineering", + "location": "nyc-office" + } + ] + }, + "roles": { + "description": "Role to assign to the user within the organization", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/commonsRole" + }, + "examples": [ + [ + { + "name": "admin" + } + ] + ] + } + } + }, + "usersUpdateMembershipResponse": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/usersUser" + } + } + }, + "commonsRegionCode": { + "type": "string", + "enum": [ + "US", + "EU" + ] + }, + "organizationsOrganizationSettingsFeature": { + "description": "Controls the activation state of a specific organization feature", + "type": "object", + "title": "Organization Feature Toggle", + "required": [ + "name", + "enabled" + ], + "properties": { + "enabled": { + "description": "Whether the feature is enabled (true) or disabled (false) for this organization", + "type": "boolean", + "examples": [ + true + ] + }, + "name": { + "description": "Feature identifier. Supported values include: \"sso\" (Single Sign-On), \"directory_sync\" (Directory Synchronization), \"domain_verification\" (Domain Verification)", + "type": "string", + "examples": [ + "sso" + ] + } + } + }, + "organizationsOrganizationSettings": { + "description": "Configuration options that control organization-level features and capabilities", + "type": "object", + "title": "Organization Settings", + "properties": { + "features": { + "description": "List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/organizationsOrganizationSettingsFeature" + }, + "examples": [ + [ + { + "enabled": true, + "name": "sso" + }, + { + "enabled": false, + "name": "directory_sync" + } + ] + ] + } + }, + "examples": [ + { + "features": [ + { + "enabled": true, + "name": "sso" + }, + { + "enabled": false, + "name": "directory_sync" + } + ] + } + ] + }, + "organizationsOrganization": { + "type": "object", + "required": [ + "create_time" + ], + "properties": { + "create_time": { + "description": "Timestamp when the organization was created", + "type": "string", + "format": "date-time", + "title": "Created Time", + "examples": [ + "2025-02-15T06:23:44.560000Z" + ] + }, + "display_name": { + "description": "Name of the organization. Must be between 1 and 200 characters", + "type": "string", + "title": "Name of the org to be used in display", + "examples": [ + "Megasoft" + ] + }, + "external_id": { + "description": "Your application's unique identifier for this organization, used to link Scalekit with your system.", + "type": "string", + "title": "External Id is useful to store a unique identifier for a given Org that. The unique Identifier can be the id of your tenant / org in your SaaSApp", + "examples": [ + "my_unique_id" + ] + }, + "id": { + "description": "Unique scalekit-generated identifier that uniquely references an organization", + "type": "string", + "title": "Id", + "examples": [ + "org_59615193906282635" + ] + }, + "metadata": { + "description": "Key value pairs extension attributes.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "region_code": { + "description": "Geographic region code for the organization. Currently limited to US.", + "title": "Optional regioncode", + "$ref": "#/components/schemas/commonsRegionCode", + "examples": [ + "US" + ] + }, + "settings": { + "title": "Organization Settings", + "$ref": "#/components/schemas/organizationsOrganizationSettings" + }, + "update_time": { + "description": "Timestamp when the organization was last updated", + "type": "string", + "format": "date-time", + "title": "Updated time", + "examples": [ + "2025-02-15T06:23:44.560000Z" + ] + } + } + }, + "organizationsListOrganizationsResponse": { + "type": "object", + "properties": { + "next_page_token": { + "description": "Pagination token for the next page of results. Use this token to fetch the next page.", + "type": "string", + "examples": [ + "" + ] + }, + "organizations": { + "description": "List of organization objects", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/organizationsOrganization" + } + }, + "prev_page_token": { + "description": "Pagination token for the previous page of results. Use this token to fetch the previous page.", + "type": "string", + "examples": [ + "" + ] + }, + "total_size": { + "description": "Total number of organizations in the environment.", + "type": "integer", + "format": "int64", + "examples": [ + 30 + ] + } + } + }, + "v1organizationsCreateOrganization": { + "type": "object", + "required": [ + "display_name" + ], + "properties": { + "display_name": { + "description": "Name of the organization. Must be between 1 and 200 characters.", + "type": "string", + "examples": [ + "Megasoft Inc" + ] + }, + "external_id": { + "description": "Your application's unique identifier for this organization, used to link Scalekit with your system.", + "type": "string", + "examples": [ + "my_unique_id" + ] + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "organizationsCreateOrganizationResponse": { + "type": "object", + "properties": { + "organization": { + "description": "The newly created organization containing its ID, settings, and metadata", + "$ref": "#/components/schemas/organizationsOrganization" + } + } + }, + "organizationsGetOrganizationResponse": { + "type": "object", + "properties": { + "organization": { + "description": "The newly created organization", + "$ref": "#/components/schemas/organizationsOrganization" + } + } + }, + "v1organizationsUpdateOrganization": { + "description": "For update messages ensure the indexes are same as the base model itself.", + "type": "object", + "properties": { + "display_name": { + "description": "Name of the organization to display in the UI. Must be between 1 and 200 characters", + "type": "string", + "examples": [ + "Acme Corporation" + ] + }, + "external_id": { + "description": "Your application's unique identifier for this organization, used to link Scalekit with your system", + "type": "string", + "examples": [ + "tenant_12345" + ] + }, + "metadata": { + "description": "Custom key-value pairs to store with the organization. Keys must be 3-25 characters, values must be 1-256 characters. Maximum 10 pairs allowed.", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "examples": [ + { + "industry": "technology" + } + ] + } + } + }, + "organizationsUpdateOrganizationResponse": { + "type": "object", + "properties": { + "organization": { + "description": "Updated organization details", + "$ref": "#/components/schemas/organizationsOrganization" + } + } + }, + "organizationsLink": { + "type": "object", + "properties": { + "expire_time": { + "description": "Expiry time of the link. The link is valid for 1 minute.", + "type": "string", + "format": "date-time", + "examples": [ + "2024-02-06T14:48:00Z" + ] + }, + "id": { + "description": "Unique Identifier for the link", + "type": "string", + "examples": [ + "lnk_123123123123123" + ] + }, + "location": { + "description": "Location of the link. This is the URL that can be used to access the Admin portal. The link is valid for 1 minute", + "type": "string", + "examples": [ + "https://scalekit.com/portal/lnk_123123123123123" + ] + } + } + }, + "organizationsGeneratePortalLinkResponse": { + "type": "object", + "properties": { + "link": { + "description": "Contains the generated admin portal link details. The link URL can be shared with organization administrators to set up: Single Sign-On (SSO) authentication and directory synchronization", + "$ref": "#/components/schemas/organizationsLink" + } + } + }, + "rolesRolePermission": { + "type": "object", + "title": "RolePermissions represents a permission with role source information", + "properties": { + "create_time": { + "type": "string", + "format": "date-time" + }, + "description": { + "type": "string" + }, + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "role_name": { + "description": "Name of the role from which this permission was sourced", + "type": "string", + "examples": [ + "admin_role" + ] + }, + "update_time": { + "type": "string", + "format": "date-time" + } + } + }, + "v1rolesRole": { + "type": "object", + "properties": { + "default_creator": { + "description": "Indicates if this role is the default creator role for new organizations.", + "type": "boolean", + "examples": [ + true + ] + }, + "default_member": { + "description": "Indicates if this role is the default member role for new users.", + "type": "boolean", + "examples": [ + true + ] + }, + "dependent_roles_count": { + "description": "Number of roles that extend from this role (dependent roles count). Read-only field.", + "type": "integer", + "format": "int32", + "examples": [ + 3 + ] + }, + "description": { + "description": "Detailed description of the role's purpose and capabilities. Maximum 2000 characters.", + "type": "string", + "examples": [ + "Can create, edit, and publish content but cannot delete or manage users" + ] + }, + "display_name": { + "description": "Human-readable display name for the role. Used in user interfaces and reports.", + "type": "string", + "examples": [ + "Content Editor" + ] + }, + "extends": { + "description": "Name of the base role that this role extends. Enables hierarchical role inheritance.", + "type": "string", + "examples": [ + "admin_role" + ] + }, + "id": { + "description": "Unique system-generated identifier for the role. Immutable once created.", + "type": "string", + "readOnly": true, + "examples": [ + "role_1234abcd5678efgh" + ] + }, + "is_org_role": { + "description": "Indicates if this role is an organization role.", + "type": "boolean", + "examples": [ + true + ] + }, + "name": { + "description": "Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters.", + "type": "string", + "examples": [ + "content_editor" + ] + }, + "permissions": { + "description": "List of permissions with role source information. Only included when 'include' parameter is specified in the request.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/rolesRolePermission" + }, + "examples": [ + [ + { + "description": "Read Content", + "name": "read:content", + "role_name": "admin_role" + }, + { + "description": "Write Content", + "name": "write:content", + "role_name": "editor_role" + } + ] + ] + } + } + }, + "rolesListOrganizationRolesResponse": { + "type": "object", + "properties": { + "roles": { + "description": "List of roles objects", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/v1rolesRole" + } + } + } + }, + "v1rolesCreateOrganizationRole": { + "type": "object", + "properties": { + "description": { + "description": "Description of the organization's role", + "type": "string", + "examples": [ + "Organization Viewer Role will be used only for viewing the objects" + ] + }, + "display_name": { + "description": "Display name of the organization's role", + "type": "string", + "examples": [ + "Organization Viewer Role" + ] + }, + "extends": { + "description": "Base role name for hierarchical roles", + "type": "string", + "examples": [ + "admin_role" + ] + }, + "name": { + "description": "Unique name of the organization's role", + "type": "string", + "examples": [ + "org_viewer_role" + ] + }, + "permissions": { + "description": "List of permission names to assign to this role. Permissions must exist in the current environment.", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "read:users", + "write:documents" + ] + ] + } + } + }, + "rolesCreateOrganizationRoleResponse": { + "type": "object", + "properties": { + "role": { + "$ref": "#/components/schemas/v1rolesRole" + } + } + }, + "rolesGetOrganizationRoleResponse": { + "type": "object", + "properties": { + "role": { + "$ref": "#/components/schemas/v1rolesRole" + } + } + }, + "v1rolesUpdateRole": { + "type": "object", + "properties": { + "description": { + "description": "Detailed description of the role's purpose, capabilities, and intended use cases. Maximum 2000 characters.", + "type": "string", + "examples": [ + "Can create, edit, publish, and approve content. Cannot delete content or manage user accounts." + ] + }, + "display_name": { + "description": "Human-readable display name for the role. Used in user interfaces, reports, and user-facing communications.", + "type": "string", + "examples": [ + "Senior Content Editor" + ] + }, + "extends": { + "description": "Name of the base role that this role extends. Enables hierarchical role inheritance where this role inherits all permissions from the base role.", + "type": "string", + "examples": [ + "content_editor" + ] + }, + "permissions": { + "description": "List of permission names to assign to this role. When provided, this replaces all existing role-permission mappings. Permissions must exist in the current environment. Maximum 100 permissions per role.", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "read:content", + "write:content", + "publish:content", + "approve:content" + ] + ] + } + } + }, + "rolesUpdateOrganizationRoleResponse": { + "type": "object", + "properties": { + "role": { + "$ref": "#/components/schemas/v1rolesRole" + } + } + }, + "RolesServiceUpdateDefaultOrganizationRolesBody": { + "type": "object", + "properties": { + "default_member_role": { + "description": "Unique name of the default member role", + "type": "string", + "examples": [ + "member" + ] + } + } + }, + "rolesUpdateDefaultOrganizationRolesResponse": { + "type": "object", + "properties": { + "default_member": { + "description": "Updated default member role", + "$ref": "#/components/schemas/v1rolesRole", + "examples": [ + { + "description": "Role for regular members", + "display_name": "Member Role", + "id": "role_0987654321", + "name": "member" + } + ] + } + } + }, + "clientsCustomClaim": { + "type": "object", + "properties": { + "key": { + "description": "The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose.", + "type": "string", + "examples": [ + "environment" + ] + }, + "value": { + "description": "The value of the custom claim. This value will be included in access tokens issued to the client.", + "type": "string", + "examples": [ + "production" + ] + } + } + }, + "clientsClientSecretStatus": { + "description": "ClientSecretStatus indicates whether a client secret can be used for authentication.\nACTIVE secrets can be used for authentication while INACTIVE secrets cannot.\n\n - INACTIVE: The secret is inactive and cannot be used for authentication", + "type": "string", + "enum": [ + "INACTIVE" + ] + }, + "clientsClientSecret": { + "description": "A secure credential used for authenticating an API client. Each client can have multiple secrets for key rotation purposes.", + "type": "object", + "title": "Client Secret", + "properties": { + "create_time": { + "description": "The timestamp when this secret was created. This field is automatically set by the server and cannot be modified.", + "type": "string", + "format": "date-time", + "examples": [ + "2024-01-05T14:48:00Z" + ] + }, + "created_by": { + "description": "The identifier of the user or system that created this secret. This field helps track who created the secret for audit and compliance purposes.", + "type": "string", + "examples": [ + "user_12345" + ] + }, + "expire_time": { + "description": "The timestamp when this secret will expire. After this time, the secret cannot be used for authentication regardless of its status. If not set, the secret does not expire.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-01-05T14:48:00Z" + ] + }, + "id": { + "description": "The unique identifier for this client secret. This ID is used to reference the secret in API requests for management operations like updating or deleting the secret.", + "type": "string", + "examples": [ + "sec_1234abcd5678efgh" + ] + }, + "last_used_time": { + "description": "The timestamp when this secret was last used for authentication. This field helps track secret usage for security monitoring and identifying unused secrets that may be candidates for rotation.", + "type": "string", + "format": "date-time", + "examples": [ + "2024-02-15T10:30:00Z" + ] + }, + "plain_secret": { + "description": "The full plaintext secret value. This field is only populated when the secret is first created and is never stored by the server. It must be securely stored by the client application as it cannot be retrieved again.", + "type": "string", + "examples": [ + "sec_1234567890abcdefghijklmnopqrstuvwxyz" + ] + }, + "secret_suffix": { + "description": "A suffix that helps identify this secret. This is the last few characters of the full secret value but is not sufficient for authentication. Helps identify which secret is being used in logs and debugging.", + "type": "string", + "examples": [ + "xyzw" + ] + }, + "status": { + "description": "The current status of this secret. A secret must be ACTIVE to be used for authentication. INACTIVE secrets cannot be used for authentication but are retained for audit purposes.", + "$ref": "#/components/schemas/clientsClientSecretStatus", + "examples": [ + "INACTIVE" + ] + }, + "update_time": { + "description": "The timestamp when this secret was last updated. This field is automatically updated by the server when the secret's status changes or other properties are modified.", + "type": "string", + "format": "date-time", + "examples": [ + "2024-01-10T09:12:00Z" + ] + } + } + }, + "clientsM2MClient": { + "type": "object", + "properties": { + "audience": { + "description": "The intended recipients of access tokens issued to this client. Each audience value should be a URI that identifies an API or service.", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "https://api.example.com" + ] + ] + }, + "client_id": { + "description": "The unique identifier for this API client. This ID is used to identify the client in API requests and logs. It is automatically generated when the client is created and cannot be modified.", + "type": "string", + "examples": [ + "m2morg_1231234233424344" + ] + }, + "create_time": { + "description": "The timestamp when this API client was created. This field is automatically set by the server and cannot be modified.", + "type": "string", + "format": "date-time", + "examples": [ + "2024-01-05T14:48:00Z" + ] + }, + "custom_claims": { + "description": "Additional claims included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/clientsCustomClaim" + } + }, + "description": { + "description": "A detailed description of the client's purpose and usage. This helps administrators understand what the client is used for.", + "type": "string", + "examples": [ + "Service account for automated deployment processes" + ] + }, + "expiry": { + "description": "Expiry time in seconds for the token generated by the client", + "type": "string", + "format": "int64", + "examples": [ + 3600 + ] + }, + "is_cimd": { + "description": "Indicates if the client was created via Client ID Metadata Document (CIMD). CIMD clients can update their own configuration according to the CIMD specification.", + "type": "boolean", + "examples": [ + false + ] + }, + "is_dcr": { + "description": "Indicates if the client was created via Dynamic Client Registration (DCR). Clients created through DCR may have different management and lifecycle policies compared to those created manually.", + "type": "boolean", + "examples": [ + false + ] + }, + "metadata_uri": { + "description": "The URI to the client's metadata, which is utilized to obtain the client's configuration details", + "type": "string", + "examples": [ + "https://example.com/client-metadata.json" + ] + }, + "name": { + "description": "The display name of the API client. This name helps identify the client in the dashboard and logs.", + "type": "string", + "examples": [ + "GitHub Actions Deployment Service" + ] + }, + "organization_id": { + "description": "The ID of the organization that owns this API client. This ID is used to associate the client with the correct organization and enforce organization-specific access controls.", + "type": "string", + "examples": [ + "org_1231234233424344" + ] + }, + "redirect_uris": { + "description": "The redirect URI for this API client. This URI is used in the OAuth 2.0 authorization flow to redirect users after authentication.", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "https://example.com/callback" + ] + ] + }, + "resource_id": { + "description": "The ID of the resource associated with this M2M client. This field is used to link the client to a specific resource in the system.", + "type": "string", + "examples": [ + "app_1231234233424344" + ] + }, + "scopes": { + "description": "The OAuth 2.0 scopes granted to this client. These scopes determine what resources and actions the client can access.", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "deploy:resources", + "read:deployments" + ] + ] + }, + "secrets": { + "description": "List of client secrets associated with this client. Each secret can be used for authentication, but only the most recently created secret is typically active. Secrets are stored securely and their values are never returned after creation.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/clientsClientSecret" + } + }, + "update_time": { + "description": "The timestamp when this API client was last updated. This field is automatically updated by the server whenever the client's configuration changes.", + "type": "string", + "format": "date-time", + "examples": [ + "2024-01-05T14:48:00Z" + ] + } + } + }, + "clientsListOrganizationClientsResponse": { + "description": "Response message containing a paginated list of API clients for the specified organization.", + "type": "object", + "title": "List Organization Clients Response", + "properties": { + "clients": { + "description": "List of API client objects for the organization. Each client includes its configuration, metadata, and active secrets (without exposing actual secret values).", + "type": "array", + "title": "List of organization API clients", + "items": { + "type": "object", + "$ref": "#/components/schemas/clientsM2MClient" + } + }, + "next_page_token": { + "description": "Pagination token for the next page of results. Use this token to fetch the next page.", + "type": "string", + "title": "Pagination token for the next page of results", + "examples": [ + "" + ] + }, + "prev_page_token": { + "description": "Pagination token for the previous page of results. Use this token to fetch the previous page.", + "type": "string", + "title": "Pagination token for the previous page of results", + "examples": [ + "" + ] + }, + "total_size": { + "description": "Total number of API clients in the organization.", + "type": "integer", + "format": "int64", + "title": "Total number of clients in the organization", + "examples": [ + 30 + ] + } + } + }, + "clientsOrganizationClient": { + "type": "object", + "properties": { + "audience": { + "description": "The intended recipients of the access tokens issued to this client. Each audience value should be a URI that identifies the API or service that will validate the token.", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "https://api.example.com/api/analytics", + "https://deployment-api.acmecorp.com" + ] + ] + }, + "custom_claims": { + "description": "Additional claims to be included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. Keep claims minimal to avoid increasing token size.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/clientsCustomClaim" + }, + "examples": [ + [ + { + "key": "environment", + "value": "production" + }, + { + "key": "service", + "value": "deployment" + } + ] + ] + }, + "description": { + "description": "A detailed explanation of the client's purpose and usage. This helps administrators understand what the client is used for and who manages it.", + "type": "string", + "examples": [ + "Service account for GitHub Actions to deploy resources to production" + ] + }, + "expiry": { + "description": "Expiry time in seconds for the token generated by the client", + "type": "string", + "format": "int64", + "examples": [ + 3600 + ] + }, + "name": { + "description": "A descriptive name for the API client that helps identify its purpose. This name is displayed in the dashboard and logs. Must be between 1 and 128 characters.", + "type": "string", + "examples": [ + "GitHub Actions Deployment Service" + ] + }, + "scopes": { + "description": "OAuth 2.0 scopes that define the permissions granted to this client. Each scope represents a specific permission or set of permissions. The client can only access resources that match its granted scopes.", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "deploy:resources", + "read:deployments" + ] + ] + } + } + }, + "clientsCreateOrganizationClientResponse": { + "type": "object", + "properties": { + "client": { + "description": "Details of the created client", + "$ref": "#/components/schemas/clientsM2MClient" + }, + "plain_secret": { + "description": "Client secret value (only returned once at creation)", + "type": "string", + "examples": [ + "CdExsdErfccxDDssddfffgfeFHH1" + ] + } + } + }, + "clientsGetOrganizationClientResponse": { + "type": "object", + "properties": { + "client": { + "description": "Details of the requested client", + "$ref": "#/components/schemas/clientsM2MClient" + } + } + }, + "clientsUpdateOrganizationClientResponse": { + "type": "object", + "properties": { + "client": { + "description": "Updated details of the client", + "$ref": "#/components/schemas/clientsM2MClient" + } + } + }, + "clientsCreateOrganizationClientSecretResponse": { + "type": "object", + "properties": { + "plain_secret": { + "description": "Client secret value (only returned once at creation)", + "type": "string", + "examples": [ + "m2morg_client_secret_xyz123" + ] + }, + "secret": { + "description": "Details of the created client secret", + "$ref": "#/components/schemas/clientsClientSecret" + } + } + }, + "connectionsConfigurationType": { + "type": "string", + "enum": [ + "DISCOVERY", + "MANUAL" + ] + }, + "domainsVerificationMethod": { + "type": "string", + "enum": [ + "ADMIN", + "DNS", + "NOT_APPLICABLE" + ] + }, + "domainsVerificationStatus": { + "type": "string", + "enum": [ + "PENDING", + "VERIFIED", + "FAILED", + "AUTO_VERIFIED" + ] + }, + "domainsDomain": { + "type": "object", + "properties": { + "create_time": { + "description": "Timestamp when the domain was first created.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-09-01T12:14:43.100000Z" + ] + }, + "domain": { + "description": "The business domain name that was configured for allowed email domain functionality (e.g., company.com, subdomain.company.com).", + "type": "string", + "examples": [ + "customerdomain.com" + ] + }, + "domain_type": { + "example": "ORGANIZATION_DOMAIN" + }, + "environment_id": { + "description": "The environment ID where this domain is configured.", + "type": "string", + "examples": [ + "env_58345499215790610" + ] + }, + "id": { + "description": "Scalekit-generated unique identifier for this domain record.", + "type": "string", + "examples": [ + "dom_88351643129225005" + ] + }, + "organization_id": { + "description": "The organization to which the domain belongs.", + "type": "string", + "examples": [ + "org_81667076086825451" + ] + }, + "update_time": { + "description": "Timestamp when the domain was last updated.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-09-01T12:14:43.110455Z" + ] + }, + "verification_method": { + "description": "Method that determines how domain ownership is verified.\n- ADMIN: domain is marked verified without DNS validation, typically by an admin.\n- DNS: domain must be verified by adding a TXT record to your DNS configuration.\n- NOT_APPLICABLE: verification does not apply to this domain type.", + "$ref": "#/components/schemas/domainsVerificationMethod", + "examples": [ + "ADMIN" + ] + }, + "verification_status": { + "description": "Verification status of the domain.\n- PENDING: DNS TXT record has not been validated yet.\n- VERIFIED: domain confirmed via DNS TXT record validation or admin approval.\n- AUTO_VERIFIED: domain verified automatically without DNS changes.\n- FAILED: DNS TXT record was not validated within the verification window.", + "$ref": "#/components/schemas/domainsVerificationStatus", + "examples": [ + "AUTO_VERIFIED" + ] + } + } + }, + "connectionsOAuthConnectionConfig": { + "type": "object", + "properties": { + "access_type": { + "description": "Access Type", + "type": "string", + "examples": [ + "offline" + ] + }, + "authorize_uri": { + "description": "Authorize URI", + "type": "string", + "examples": [ + "https://youridp.com/service/oauth/authorize" + ] + }, + "client_id": { + "description": "Client ID", + "type": "string", + "examples": [ + "oauth_client_id" + ] + }, + "client_secret": { + "description": "Client Secret", + "type": "string", + "examples": [ + "oauth_client_secret" + ] + }, + "custom_scope_name": { + "description": "Custom Scope Name", + "type": "string", + "examples": [ + "user_scope" + ] + }, + "pkce_enabled": { + "description": "PKCE Enabled", + "type": "boolean", + "examples": [ + true + ] + }, + "prompt": { + "description": "Prompt for the user", + "type": "string", + "examples": [ + "none" + ] + }, + "redirect_uri": { + "description": "Redirect URI", + "type": "string", + "examples": [ + "https://yourapp.com/service/oauth/redirect" + ] + }, + "scopes": { + "description": "OIDC Scopes", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "openid", + "profile" + ] + ] + }, + "sync_user_profile_on_login": { + "description": "Indicates whether user profiles should be synchronized with the identity provider upon each log-in.", + "type": "boolean", + "examples": [ + true + ] + }, + "tenant_id": { + "description": "Microsoft Entra tenant ID. Required when using a single-tenant or multi-tenant app registered in Microsoft Entra. Leave empty to use the common endpoint.", + "type": "string", + "examples": [ + "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + ] + }, + "token_access_type": { + "description": "Token Access Type", + "type": "string", + "examples": [ + "offline" + ] + }, + "token_uri": { + "description": "Token URI", + "type": "string", + "examples": [ + "https://youridp.com/service/oauth/token" + ] + }, + "use_platform_creds": { + "description": "Use Scalekit credentials", + "type": "boolean", + "examples": [ + true + ] + }, + "user_info_uri": { + "description": "User Info URI", + "type": "string", + "examples": [ + "https://youridp.com/service/oauth/userinfo" + ] + } + } + }, + "connectionsOIDCScope": { + "type": "string", + "enum": [ + "openid", + "profile", + "email", + "address", + "phone" + ] + }, + "connectionsTokenAuthType": { + "type": "string", + "enum": [ + "URL_PARAMS", + "BASIC_AUTH" + ] + }, + "connectionsOIDCConnectionConfig": { + "type": "object", + "properties": { + "authorize_uri": { + "description": "Authorize URI", + "type": "string", + "examples": [ + "https://youridp.com/service/oauth/authorize" + ] + }, + "backchannel_logout_redirect_uri": { + "description": "backchannel logout redirect uri where idp sends logout_token", + "type": "string", + "readOnly": true, + "examples": [ + "https://yourapp.com/sso/v1/oidc/conn_1234/backchannel-logout" + ] + }, + "client_id": { + "description": "Client ID", + "type": "string", + "examples": [ + "oauth_client_id" + ] + }, + "client_secret": { + "description": "Client Secret", + "type": "string", + "examples": [ + "oauth_client_secret" + ] + }, + "discovery_endpoint": { + "description": "Discovery Endpoint", + "type": "string", + "examples": [ + "https://youridp.com/service/oauth/.well-known/openid-configuration" + ] + }, + "idp_logout_required": { + "description": "Enable IDP logout", + "type": "boolean", + "examples": [ + true + ] + }, + "issuer": { + "description": "Issuer URL", + "type": "string", + "examples": [ + "https://youridp.com/service/oauth" + ] + }, + "jit_provisioning_with_sso_enabled": { + "description": "Indicates if Just In Time user provisioning is enabled for the connection", + "type": "boolean", + "examples": [ + true + ] + }, + "jwks_uri": { + "description": "JWKS URI", + "type": "string", + "examples": [ + "https://youridp.com/service/oauth/jwks" + ] + }, + "pkce_enabled": { + "description": "PKCE Enabled", + "type": "boolean", + "examples": [ + true + ] + }, + "post_logout_redirect_uri": { + "description": "post logout redirect uri", + "type": "string", + "readOnly": true, + "examples": [ + "https://yourapp.com/sso/v1/oidc/conn_1234/logout/callback" + ] + }, + "redirect_uri": { + "description": "Redirect URI", + "type": "string", + "examples": [ + "https://yourapp.com/sso/v1/oidc/conn_1234/callback" + ] + }, + "scopes": { + "description": "OIDC Scopes", + "type": "array", + "items": { + "$ref": "#/components/schemas/connectionsOIDCScope" + }, + "examples": [ + [ + "openid", + "profile" + ] + ] + }, + "sync_user_profile_on_login": { + "description": "Indicates whether user profiles should be synchronized with the identity provider upon each log-in.", + "type": "boolean", + "examples": [ + true + ] + }, + "token_auth_type": { + "description": "Token Auth Type", + "$ref": "#/components/schemas/connectionsTokenAuthType", + "examples": [ + "URL_PARAMS" + ] + }, + "token_uri": { + "description": "Token URI", + "type": "string", + "examples": [ + "https://youridp.com/service/oauth/token" + ] + }, + "user_info_uri": { + "description": "User Info URI", + "type": "string", + "examples": [ + "https://youridp.com/service/oauth/userinfo" + ] + } + } + }, + "connectionsCodeChallengeType": { + "type": "string", + "enum": [ + "NUMERIC", + "ALPHANUMERIC" + ] + }, + "connectionsPasswordlessType": { + "type": "string", + "enum": [ + "LINK", + "OTP", + "LINK_OTP" + ] + }, + "connectionsPasswordLessConfig": { + "type": "object", + "properties": { + "code_challenge_length": { + "description": "Code Challenge Length", + "type": "integer", + "format": "int64", + "examples": [ + 6 + ] + }, + "code_challenge_type": { + "description": "Code Challenge Type", + "$ref": "#/components/schemas/connectionsCodeChallengeType", + "examples": [ + "NUMERIC" + ] + }, + "enforce_same_browser_origin": { + "description": "Enforce Same Browser Origin", + "type": "boolean", + "examples": [ + true + ] + }, + "frequency": { + "description": "Link Frequency", + "type": "integer", + "format": "int64", + "examples": [ + 1 + ] + }, + "regenerate_passwordless_credentials_on_resend": { + "description": "Regenerate the ", + "type": "boolean", + "examples": [ + true + ] + }, + "type": { + "description": "Passwordless Type", + "$ref": "#/components/schemas/connectionsPasswordlessType", + "examples": [ + "LINK" + ] + }, + "validity": { + "description": "Link Validity in Seconds", + "type": "integer", + "format": "int64", + "examples": [ + 600 + ] + } + } + }, + "connectionsIDPCertificate": { + "type": "object", + "properties": { + "certificate": { + "description": "IDP Certificate", + "type": "string" + }, + "create_time": { + "description": "Certificate Creation Time", + "type": "string", + "format": "date-time", + "examples": [ + "2021-09-01T00:00:00Z" + ] + }, + "expiry_time": { + "description": "Certificate Expiry Time", + "type": "string", + "format": "date-time", + "examples": [ + "2021-09-01T00:00:00Z" + ] + }, + "id": { + "description": "Certificate ID", + "type": "string", + "examples": [ + "cert_123123123123" + ] + }, + "issuer": { + "description": "Certificate Issuer", + "type": "string", + "examples": [ + "https://youridp.com/service/saml" + ] + } + } + }, + "connectionsNameIdFormat": { + "type": "string", + "enum": [ + "UNSPECIFIED", + "EMAIL", + "TRANSIENT", + "PERSISTENT" + ] + }, + "connectionsRequestBinding": { + "type": "string", + "enum": [ + "HTTP_POST", + "HTTP_REDIRECT" + ] + }, + "connectionsSAMLSigningOptions": { + "type": "string", + "title": "enums all", + "enum": [ + "NO_SIGNING", + "SAML_ONLY_RESPONSE_SIGNING", + "SAML_ONLY_ASSERTION_SIGNING", + "SAML_RESPONSE_ASSERTION_SIGNING", + "SAML_RESPONSE_OR_ASSERTION_SIGNING" + ] + }, + "connectionsSAMLConnectionConfigResponse": { + "type": "object", + "properties": { + "allow_idp_initiated_login": { + "description": "Allow IDP Initiated Login", + "type": "boolean", + "examples": [ + true + ] + }, + "assertion_encrypted": { + "description": "Assertion Encrypted", + "type": "boolean", + "examples": [ + true + ] + }, + "certificate_id": { + "description": "Certificate ID", + "type": "string", + "examples": [ + "cer_35585423166144613" + ] + }, + "default_redirect_uri": { + "description": "Default Redirect URI", + "type": "string", + "examples": [ + "https://yourapp.com/service/saml/redirect" + ] + }, + "force_authn": { + "description": "Force Authn", + "type": "boolean", + "examples": [ + true + ] + }, + "idp_certificates": { + "description": "IDP Certificates", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/connectionsIDPCertificate" + } + }, + "idp_entity_id": { + "description": "IDP Entity ID", + "type": "string", + "examples": [ + "https://youridp.com/service/saml" + ] + }, + "idp_metadata_url": { + "description": "IDP Metadata URL", + "type": "string", + "examples": [ + "https://youridp.com/service/saml/metadata" + ] + }, + "idp_name_id_format": { + "description": "IDP Name ID Format", + "$ref": "#/components/schemas/connectionsNameIdFormat", + "examples": [ + "EMAIL" + ] + }, + "idp_slo_request_binding": { + "description": "IDP SLO Request Binding", + "$ref": "#/components/schemas/connectionsRequestBinding", + "examples": [ + "HTTP_POST" + ] + }, + "idp_slo_required": { + "description": "Enable IDP logout", + "type": "boolean", + "examples": [ + true + ] + }, + "idp_slo_url": { + "description": "IDP SLO URL", + "type": "string", + "examples": [ + "https://youridp.com/service/saml/slo" + ] + }, + "idp_sso_request_binding": { + "description": "IDP SSO Request Binding", + "$ref": "#/components/schemas/connectionsRequestBinding", + "examples": [ + "HTTP_POST" + ] + }, + "idp_sso_url": { + "description": "IDP SSO URL", + "type": "string", + "examples": [ + "https://youridp.com/service/saml/sso" + ] + }, + "jit_provisioning_with_sso_enabled": { + "description": "Indicates if Just In Time user provisioning is enabled for the connection", + "type": "boolean", + "examples": [ + true + ] + }, + "saml_signing_option": { + "description": "SAML Signing Option", + "$ref": "#/components/schemas/connectionsSAMLSigningOptions", + "examples": [ + "SAML_ONLY_RESPONSE_SIGNING" + ] + }, + "sp_assertion_url": { + "description": "SP Assertion URL", + "type": "string", + "examples": [ + "https://youridp.com/service/saml/assertion" + ] + }, + "sp_entity_id": { + "description": "SP Entity ID", + "type": "string", + "examples": [ + "https://yourapp.com/service/saml" + ] + }, + "sp_metadata_url": { + "description": "SP Metadata URL", + "type": "string", + "examples": [ + "https://youridp.com/service/saml/metadata" + ] + }, + "sp_slo_url": { + "description": "Service Provider SLO url", + "type": "string", + "readOnly": true, + "examples": [ + "https://yourapp.com/sso/v1/saml/conn_1234/slo/callback" + ] + }, + "sync_user_profile_on_login": { + "description": "Indicates whether user profiles should be synchronized with the identity provider upon each log-in.", + "type": "boolean", + "examples": [ + true + ] + }, + "ui_button_title": { + "description": "UI Button Title", + "type": "string", + "examples": [ + "Login with SSO" + ] + }, + "want_request_signed": { + "description": "Want Request Signed", + "type": "boolean", + "examples": [ + true + ] + } + } + }, + "connectionsStaticAuthConfig": { + "type": "object", + "properties": { + "static_config": { + "type": "object" + } + } + }, + "WebAuthConfigurationAttestation": { + "type": "object", + "title": "Attestation preferences for registration", + "properties": { + "conveyance_preference": { + "type": "string", + "title": "Conveyance preference" + }, + "enterprise_approved_ids": { + "type": "array", + "title": "Enterprise-approved IDs (optional allowlist when enterprise attestation is used)", + "items": { + "type": "string" + } + } + } + }, + "WebAuthConfigurationAuthenticatorSelection": { + "type": "object", + "properties": { + "authenticator_attachment": { + "type": "string" + }, + "user_verification": { + "type": "string", + "title": "User verification requirement" + } + } + }, + "WebAuthConfigurationAuthenticators": { + "type": "object", + "properties": { + "desired_authenticator_status": { + "description": "provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate_status set to true.", + "type": "array", + "items": { + "type": "string", + "default": "[]" + } + }, + "undesired_authenticator_status": { + "description": "provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate_status set to true.", + "type": "array", + "items": { + "type": "string", + "default": "['ATTESTATION_KEY_COMPROMISE', 'USER_VERIFICATION_BYPASS', 'USER_KEY_REMOTE_COMPROMISE', 'USER_KEY_PHYSICAL_COMPROMISE', 'REVOKED']" + } + }, + "validate_anchors": { + "description": "when set to true enables the validation of the attestation statement against the trust anchor from the metadata statement.", + "type": "boolean" + }, + "validate_attestation_type": { + "description": "when set to true enables the validation of the attestation statements type against the known types the authenticator can produce.", + "type": "boolean" + }, + "validate_entry": { + "description": "requires that the provided metadata has an entry for the given authenticator to be considered valid. By default an AAGUID which has a zero value should fail validation if validate_entry_permit_zero_aaguid is not provided with the value of true.", + "type": "boolean" + }, + "validate_entry_permit_zero_aaguid": { + "description": "is an option that permits a zero'd AAGUID from an attestation statement to automatically pass metadata validations. Generally helpful to use with validate_entry.", + "type": "boolean" + }, + "validate_status": { + "description": "when set to true enables the validation of the attestation statements AAGUID against the desired and undesired lists", + "type": "boolean" + } + } + }, + "WebAuthConfigurationRp": { + "type": "object", + "title": "Rp contains relying party identifiers and origins", + "properties": { + "ids": { + "type": "array", + "title": "Relying party IDs (derived from environment domain and verified custom domain)\nAt least one required; must be hostnames without scheme or path", + "items": { + "type": "string" + } + }, + "origins": { + "type": "array", + "title": "Allowed origins corresponding to the RP IDs (https://)\nAt least one required; must be HTTPS origins", + "items": { + "type": "string" + } + } + } + }, + "WebAuthConfigurationTimeout": { + "type": "object", + "properties": { + "login": { + "description": "Login timeout duration", + "type": "string", + "default": "\"300s\"" + }, + "login_uvd": { + "description": "Login timeout duration when user verification is discouraged", + "type": "string", + "default": "\"300s\"" + }, + "registration": { + "description": "Registration timeout duration", + "type": "string", + "default": "\"300s\"" + }, + "registration_uvd": { + "description": "Registration timeout duration when user verification is discouraged", + "type": "string", + "default": "\"300s\"" + } + } + }, + "connectionsWebAuthConfiguration": { + "type": "object", + "title": "WebAuthConfiguration defines WebAuthn (passkeys) configuration limited to RP and Attestation", + "properties": { + "attestation": { + "$ref": "#/components/schemas/WebAuthConfigurationAttestation" + }, + "authenticator_selection": { + "$ref": "#/components/schemas/WebAuthConfigurationAuthenticatorSelection" + }, + "authenticators": { + "$ref": "#/components/schemas/WebAuthConfigurationAuthenticators" + }, + "enable_auto_registration": { + "description": "Enable auto registration for WebAuthn", + "type": "boolean" + }, + "enable_conditional_login": { + "description": "Allow autofill of passkeys in login page", + "type": "boolean" + }, + "rp": { + "$ref": "#/components/schemas/WebAuthConfigurationRp" + }, + "show_passkey_button": { + "description": "Show passkey button on login screen", + "type": "boolean" + }, + "timeout": { + "$ref": "#/components/schemas/WebAuthConfigurationTimeout" + } + } + }, + "connectionsConnection": { + "type": "object", + "properties": { + "attribute_mapping": { + "description": "Maps identity provider attributes to user profile fields. For example, {'email': 'user.mail', 'name': 'user.displayName'}.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "configuration_type": { + "description": "How the connection was configured: DISCOVERY (automatic configuration) or MANUAL (administrator configured)", + "$ref": "#/components/schemas/connectionsConfigurationType", + "examples": [ + "MANUAL" + ] + }, + "debug_enabled": { + "description": "Enables testing mode that allows non-HTTPS endpoints. Should only be enabled in development environments, never in production.", + "type": "boolean", + "examples": [ + true + ] + }, + "domains": { + "description": "Domain associated with this connection, used for domain-based authentication flows.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/domainsDomain" + }, + "examples": [ + [ + { + "name": "example.com" + } + ] + ] + }, + "enabled": { + "description": "Controls whether users can sign in using this connection. When false, the connection exists but cannot be used for authentication.", + "type": "boolean", + "examples": [ + false + ] + }, + "id": { + "description": "Unique identifier for this connection. Used in API calls to reference this specific connection.", + "type": "string", + "examples": [ + "conn_2123312131125533" + ] + }, + "key_id": { + "description": "Alternative identifier for this connection, typically used in frontend applications or URLs.", + "type": "string" + }, + "oauth_config": { + "description": "Configuration details for OAuth connections. Present only when type is OAUTH.", + "$ref": "#/components/schemas/connectionsOAuthConnectionConfig" + }, + "oidc_config": { + "description": "Configuration details for OpenID Connect (OIDC) connections. Present only when type is OIDC.", + "$ref": "#/components/schemas/connectionsOIDCConnectionConfig" + }, + "organization_id": { + "description": "Identifier of the organization that owns this connection. Connections are typically scoped to a single organization.", + "type": "string", + "examples": [ + "org_2123312131125533" + ] + }, + "passwordless_config": { + "description": "Configuration details for Magic Link authentication. Present only when type is MAGIC_LINK.", + "$ref": "#/components/schemas/connectionsPasswordLessConfig" + }, + "provider": { + "description": "Identity provider service that handles authentication (such as OKTA, Google, Azure AD, or a custom provider)", + "$ref": "#/components/schemas/connectionsConnectionProvider", + "examples": [ + "OKTA" + ] + }, + "provider_key": { + "description": "Key ID of the identity provider service that handles authentication", + "type": "string", + "examples": [ + "google" + ] + }, + "saml_config": { + "description": "Configuration details for SAML connections. Present only when type is SAML.", + "$ref": "#/components/schemas/connectionsSAMLConnectionConfigResponse" + }, + "static_config": { + "description": "Static configuration for custom connections. Present only when type is BASIC, BEARER, API_KEY, or custom.", + "$ref": "#/components/schemas/connectionsStaticAuthConfig" + }, + "status": { + "description": "Current configuration status of the connection. Possible values include IN_PROGRESS, CONFIGURED, and ERROR.", + "$ref": "#/components/schemas/connectionsConnectionStatus", + "readOnly": true, + "examples": [ + "IN_PROGRESS" + ] + }, + "test_connection_uri": { + "description": "URI that can be used to test this connection. Visit this URL to verify the connection works correctly.", + "type": "string", + "examples": [ + "https://auth.example.com/test-connection/conn_2123312131125533" + ] + }, + "type": { + "description": "Authentication protocol used by this connection. Can be OIDC (OpenID Connect), SAML, OAUTH, or MAGIC_LINK.", + "$ref": "#/components/schemas/connectionsConnectionType", + "examples": [ + "OIDC" + ] + }, + "webauthn_config": { + "description": "Configuration details for WebAuthn (passkeys). Present only when type is WEBAUTHN.", + "$ref": "#/components/schemas/connectionsWebAuthConfiguration" + } + } + }, + "connectionsGetConnectionResponse": { + "type": "object", + "properties": { + "connection": { + "description": "Complete connection details including provider configuration, protocol settings, status, and all metadata. Contains everything needed to understand the connection's current state.", + "$ref": "#/components/schemas/connectionsConnection" + } + } + }, + "connectionsToggleConnectionResponse": { + "type": "object", + "properties": { + "enabled": { + "description": "Current state of the connection after the operation. True means the connection is now enabled and can be used for authentication.", + "type": "boolean", + "examples": [ + true + ] + }, + "error_message": { + "description": "Error message if the operation fails", + "type": "string", + "examples": [ + "placeholder" + ] + } + } + }, + "directoriesAttributeMapping": { + "type": "object", + "properties": { + "key": { + "type": "string" + }, + "map_to": { + "type": "string" + } + } + }, + "directoriesAttributeMappings": { + "type": "object", + "properties": { + "attributes": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/directoriesAttributeMapping" + } + } + } + }, + "directoriesDirectoryProvider": { + "type": "string", + "enum": [ + "OKTA", + "GOOGLE", + "MICROSOFT_AD", + "AUTH0", + "ONELOGIN", + "JUMPCLOUD", + "PING_IDENTITY" + ] + }, + "directoriesDirectoryType": { + "type": "string", + "enum": [ + "SCIM", + "LDAP", + "POLL" + ] + }, + "directoriesRoleAssignment": { + "type": "object", + "properties": { + "group_id": { + "description": "group ID for the role mapping", + "type": "string", + "examples": [ + "dirgroup_121312434123" + ] + }, + "role_name": { + "type": "string" + } + } + }, + "directoriesRoleAssignments": { + "type": "object", + "properties": { + "assignments": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/directoriesRoleAssignment" + } + } + } + }, + "directoriesSecretStatus": { + "type": "string", + "enum": [ + "INACTIVE" + ] + }, + "directoriesSecret": { + "type": "object", + "properties": { + "create_time": { + "description": "Creation Time", + "type": "string", + "format": "date-time", + "examples": [ + "2024-10-01T00:00:00Z" + ] + }, + "directory_id": { + "description": "Directory ID", + "type": "string", + "examples": [ + "dir_12362474900684814" + ] + }, + "expire_time": { + "description": "Expiry Time", + "type": "string", + "format": "date-time", + "examples": [ + "2025-10-01T00:00:00Z" + ] + }, + "id": { + "type": "string" + }, + "last_used_time": { + "description": "Last Used Time", + "type": "string", + "format": "date-time", + "examples": [ + "2024-10-01T00:00:00Z" + ] + }, + "secret_suffix": { + "description": "Secret Suffix", + "type": "string", + "examples": [ + "Nzg5" + ] + }, + "status": { + "description": "Secret Status", + "$ref": "#/components/schemas/directoriesSecretStatus", + "examples": [ + "INACTIVE" + ] + } + } + }, + "directoriesStats": { + "type": "object", + "properties": { + "group_updated_at": { + "description": "Max time of Group Updated At for Directory", + "type": "string", + "format": "date-time", + "examples": [ + "2024-10-01T00:00:00Z" + ] + }, + "total_groups": { + "description": "Total Groups in the Directory", + "type": "integer", + "format": "int32", + "examples": [ + 10 + ] + }, + "total_users": { + "description": "Total Users in the Directory", + "type": "integer", + "format": "int32", + "examples": [ + 10 + ] + }, + "user_updated_at": { + "description": "Max time of User Updated At for Directory", + "type": "string", + "format": "date-time", + "examples": [ + "2024-10-01T00:00:00Z" + ] + } + } + }, + "directoriesDirectory": { + "type": "object", + "properties": { + "attribute_mappings": { + "description": "Mappings between directory attributes and Scalekit user and group attributes", + "$ref": "#/components/schemas/directoriesAttributeMappings" + }, + "directory_endpoint": { + "description": "The endpoint URL generated by Scalekit for synchronizing users and groups from the Directory Provider", + "type": "string", + "examples": [ + "https://yourapp.scalekit.com/api/v1/directoies/dir_123212312/scim/v2" + ] + }, + "directory_provider": { + "description": "Identity provider connected to this directory", + "$ref": "#/components/schemas/directoriesDirectoryProvider", + "examples": [ + "OKTA" + ] + }, + "directory_type": { + "description": "Type of the directory, indicating the protocol or standard used for synchronization", + "$ref": "#/components/schemas/directoriesDirectoryType", + "examples": [ + "SCIM" + ] + }, + "email": { + "description": "Email Id associated with Directory whose access will be used for polling", + "type": "string", + "examples": [ + "john.doe@scalekit.cloud" + ] + }, + "enabled": { + "description": "Indicates whether the directory is currently enabled and actively synchronizing users and groups", + "type": "boolean", + "examples": [ + true + ] + }, + "groups_tracked": { + "description": "It indicates if all groups are tracked or select groups are tracked", + "type": "string", + "examples": [ + "ALL" + ] + }, + "id": { + "description": "Unique identifier of the directory", + "type": "string", + "examples": [ + "dir_121312434123312" + ] + }, + "last_synced_at": { + "description": "Timestamp of the last successful synchronization of users and groups from the Directory Provider", + "type": "string", + "format": "date-time", + "examples": [ + "2024-10-01T00:00:00Z" + ] + }, + "name": { + "description": "Name of the directory, typically representing the connected Directory provider", + "type": "string", + "examples": [ + "Azure AD" + ] + }, + "organization_id": { + "description": "Unique identifier of the organization to which the directory belongs", + "type": "string", + "examples": [ + "org_121312434123312" + ] + }, + "role_assignments": { + "description": "Role assignments associated with the directory, defining group based role assignments", + "$ref": "#/components/schemas/directoriesRoleAssignments" + }, + "secrets": { + "description": "List of secrets used for authenticating and synchronizing with the Directory Provider", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/directoriesSecret" + } + }, + "stats": { + "description": "Statistics and metrics related to the directory, such as synchronization status and error counts", + "$ref": "#/components/schemas/directoriesStats" + }, + "status": { + "description": "Directory Status", + "type": "string", + "examples": [ + "IN_PROGRESS" + ] + }, + "total_groups": { + "description": "Total number of groups in the directory", + "type": "integer", + "format": "int32", + "examples": [ + 10 + ] + }, + "total_users": { + "description": "Total number of users in the directory", + "type": "integer", + "format": "int32", + "examples": [ + 10 + ] + } + } + }, + "directoriesListDirectoriesResponse": { + "type": "object", + "properties": { + "directories": { + "description": "List of directories associated with the organization", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/directoriesDirectory" + } + } + } + }, + "directoriesDirectoryGroup": { + "type": "object", + "properties": { + "display_name": { + "description": "Display Name", + "type": "string", + "examples": [ + "Admins" + ] + }, + "group_detail": { + "description": "Complete Group Details Payload", + "type": "object" + }, + "id": { + "description": "Group ID", + "type": "string", + "examples": [ + "dirgroup_121312434123312" + ] + }, + "total_users": { + "description": "Total Users in the Group", + "type": "integer", + "format": "int32", + "examples": [ + 10 + ] + }, + "updated_at": { + "description": "Updated At", + "type": "string", + "format": "date-time", + "examples": [ + "2024-10-01T00:00:00Z" + ] + } + } + }, + "directoriesListDirectoryGroupsResponse": { + "type": "object", + "properties": { + "groups": { + "description": "List of directory groups retrieved from the specified directory", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/directoriesDirectoryGroup" + } + }, + "next_page_token": { + "description": "Token to retrieve the next page of results. Use this token in the 'page_token' field of the next request", + "type": "string" + }, + "prev_page_token": { + "description": "Token to retrieve the previous page of results. Use this token in the 'page_token' field of the next request", + "type": "string" + }, + "total_size": { + "description": "Total number of groups matching the request criteria, regardless of pagination", + "type": "integer", + "format": "int64" + } + } + }, + "directoriesDirectoryUser": { + "type": "object", + "properties": { + "email": { + "description": "Email", + "type": "string", + "examples": [ + "johndoe" + ] + }, + "emails": { + "description": "Emails", + "type": "array", + "items": { + "type": "string" + } + }, + "family_name": { + "description": "Last Name", + "type": "string", + "examples": [ + "Doe" + ] + }, + "given_name": { + "description": "First Name", + "type": "string", + "examples": [ + "John" + ] + }, + "groups": { + "description": "Groups", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/directoriesDirectoryGroup" + } + }, + "id": { + "description": "User ID", + "type": "string", + "examples": [ + "diruser_121312434123312" + ] + }, + "preferred_username": { + "description": "Preferred Username", + "type": "string", + "examples": [ + "johndoe" + ] + }, + "updated_at": { + "description": "Updated At", + "type": "string", + "format": "date-time", + "examples": [ + "2024-10-01T00:00:00Z" + ] + }, + "user_detail": { + "description": "Complete User Details Payload", + "type": "object" + } + } + }, + "directoriesListDirectoryUsersResponse": { + "type": "object", + "properties": { + "next_page_token": { + "description": "Token for pagination. Use this token in the 'page_token' field of the next request to fetch the subsequent page of users", + "type": "string" + }, + "prev_page_token": { + "description": "Token for pagination. Use this token in the 'page_token' field of the next request to fetch the prior page of users", + "type": "string" + }, + "total_size": { + "description": "Total number of users available in the directory that match the request criteria", + "type": "integer", + "format": "int64" + }, + "users": { + "description": "List of directory users retrieved from the specified directory", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/directoriesDirectoryUser" + } + } + } + }, + "directoriesGetDirectoryResponse": { + "type": "object", + "properties": { + "directory": { + "description": "Detailed information about the requested directory", + "$ref": "#/components/schemas/directoriesDirectory" + } + } + }, + "directoriesToggleDirectoryResponse": { + "type": "object", + "properties": { + "enabled": { + "description": "Specifies the directory's state after the toggle operation. A value of `true` indicates that the directory is enabled and actively synchronizing users and groups. A value of `false` means the directory is disabled, halting synchronization", + "type": "boolean", + "examples": [ + true + ] + }, + "error_message": { + "description": "Contains a human-readable error message if the toggle operation encountered an issue. If the operation was successful, this field will be empty", + "type": "string", + "examples": [ + "The directory is already enabled" + ] + } + } + }, + "domainsListDomainResponse": { + "type": "object", + "properties": { + "domains": { + "description": "Array of domain objects containing all domain details including verification status and configuration.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/domainsDomain" + } + }, + "page_number": { + "description": "Current page number in the pagination sequence.", + "type": "integer", + "format": "int32", + "examples": [ + 1 + ] + }, + "page_size": { + "description": "Number of domains returned in this page.", + "type": "integer", + "format": "int32", + "examples": [ + 1 + ] + } + } + }, + "domainsDomainType": { + "type": "string", + "enum": [ + "ALLOWED_EMAIL_DOMAIN", + "ORGANIZATION_DOMAIN" + ], + "x-enum-varnames": [ + "ORGANIZATION_DOMAIN", + "ALLOWED_EMAIL_DOMAIN" + ] + }, + "v1domainsCreateDomain": { + "type": "object", + "properties": { + "domain": { + "description": "The domain name to be configured. Must be a valid business domain you control. Public and disposable domains (gmail.com, outlook.com, etc.) are automatically blocked for security.", + "type": "string", + "examples": [ + "customerdomain.com" + ] + }, + "domain_type": { + "description": "The domain type.\n- ALLOWED_EMAIL_DOMAIN: trusted domain used to suggest the organization in the organization switcher during sign-in/sign-up.\n- ORGANIZATION_DOMAIN: SSO discovery domain used to route users to the correct SSO provider and enforce SSO.\n", + "$ref": "#/components/schemas/domainsDomainType", + "examples": [ + "ORGANIZATION_DOMAIN" + ] + } + } + }, + "domainsCreateDomainResponse": { + "type": "object", + "properties": { + "domain": { + "description": "The newly created domain object with all configuration details and system-generated identifiers.", + "$ref": "#/components/schemas/domainsDomain" + } + } + }, + "domainsGetDomainResponse": { + "type": "object", + "properties": { + "domain": { + "description": "The requested domain object with complete details including domain type, timestamps and configuration.", + "$ref": "#/components/schemas/domainsDomain" + } + } + }, + "organizationsOrganizationUserManagementSettings": { + "type": "object", + "properties": { + "max_allowed_users": { + "description": "Maximum number of users allowed in the organization. When nil (not set), there feature is not enabled. When explicitly set to zero, it also means no limit. When set to a positive integer, it enforces the maximum user limit.", + "type": "integer", + "format": "int32", + "examples": [ + 100 + ] + } + } + }, + "OrganizationServiceUpsertUserManagementSettingsBody": { + "type": "object", + "properties": { + "settings": { + "description": "The new values for the setting fields to patch.", + "$ref": "#/components/schemas/organizationsOrganizationUserManagementSettings" + } + } + }, + "organizationsUpsertUserManagementSettingsResponse": { + "type": "object", + "properties": { + "settings": { + "description": "The updated setting.", + "$ref": "#/components/schemas/organizationsOrganizationUserManagementSettings" + } + } + }, + "usersListOrganizationUsersResponse": { + "type": "object", + "properties": { + "next_page_token": { + "description": "Opaque token for retrieving the next page of results. Empty if there are no more pages.", + "type": "string", + "examples": [ + "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=" + ] + }, + "prev_page_token": { + "description": "Opaque token for retrieving the previous page of results. Empty for the first page.", + "type": "string", + "examples": [ + "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9" + ] + }, + "total_size": { + "description": "Total number of users matching the request criteria, regardless of pagination.", + "type": "integer", + "format": "int64", + "examples": [ + 1042 + ] + }, + "users": { + "description": "List of user objects for the current page. May contain fewer entries than requested page_size.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/usersUser" + } + } + } + }, + "usersCreateUserProfile": { + "type": "object", + "properties": { + "custom_attributes": { + "description": "Custom attributes for extended user profile data. Keys (3-25 chars), values (1-256 chars).", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "examples": [ + { + "department": "engineering", + "security_clearance": "level2" + } + ] + }, + "family_name": { + "description": "User's family name. Maximum 255 characters.", + "type": "string", + "examples": [ + "Doe" + ] + }, + "gender": { + "description": "User's gender identity.", + "type": "string", + "examples": [ + "male" + ] + }, + "given_name": { + "description": "User's given name. Maximum 255 characters.", + "type": "string", + "examples": [ + "John" + ] + }, + "groups": { + "description": "List of group names the user belongs to. Each group name must be 1-250 characters", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "engineering", + "managers" + ] + ] + }, + "locale": { + "description": "User's localization preference in BCP-47 format. Defaults to organization settings.", + "type": "string", + "examples": [ + "en-US" + ] + }, + "metadata": { + "description": "System-managed key-value pairs for internal tracking. Keys (3-25 chars), values (1-256 chars).", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "examples": [ + { + "account_status": "active", + "signup_source": "mobile_app" + } + ] + }, + "name": { + "description": "Full name in display format. Typically combines first_name and last_name.", + "type": "string", + "examples": [ + "John Michael Doe" + ] + }, + "phone_number": { + "description": "Phone number in E.164 international format. Required for SMS-based authentication.", + "type": "string", + "examples": [ + "+14155552671" + ] + }, + "picture": { + "description": "URL to the user's profile picture or avatar.", + "type": "string", + "examples": [ + "https://example.com/avatar.jpg" + ] + }, + "preferred_username": { + "description": "User's preferred username for display purposes.", + "type": "string", + "examples": [ + "John Michael Doe" + ] + } + } + }, + "usersCreateUser": { + "type": "object", + "properties": { + "email": { + "description": "Primary email address for the user. Must be unique across the environment and valid per RFC 5322.", + "type": "string", + "examples": [ + "user@example.com" + ] + }, + "external_id": { + "description": "Your application's unique identifier for this organization, used to link Scalekit with your system.", + "type": "string", + "examples": [ + "ext_12345a67b89c" + ] + }, + "membership": { + "description": "List of organization memberships. Automatically populated based on group assignments.", + "$ref": "#/components/schemas/v1usersCreateMembership" + }, + "metadata": { + "description": "Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars).", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "examples": [ + { + "department": "engineering", + "location": "nyc-office" + } + ] + }, + "user_profile": { + "description": "User's personal information including name, address, and other profile attributes.", + "$ref": "#/components/schemas/usersCreateUserProfile" + } + } + }, + "usersCreateUserAndMembershipResponse": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/usersUser" + } + } + }, + "usersPermission": { + "type": "object", + "properties": { + "description": { + "description": "Description of what the permission allows", + "type": "string", + "examples": [ + "Allows creating new user accounts" + ] + }, + "id": { + "description": "Unique identifier for the permission", + "type": "string", + "readOnly": true, + "examples": [ + "perm_1234abcd5678efgh" + ] + }, + "name": { + "description": "Unique name identifier for the permission", + "type": "string", + "examples": [ + "users:create" + ] + } + } + }, + "usersListUserPermissionsResponse": { + "type": "object", + "properties": { + "permissions": { + "description": "List of permissions the user has access to", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/usersPermission" + } + } + } + }, + "usersListUserRolesResponse": { + "type": "object", + "properties": { + "roles": { + "description": "List of roles assigned to the user", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/commonsRole" + } + } + } + }, + "usersSearchOrganizationUsersResponse": { + "type": "object", + "properties": { + "next_page_token": { + "description": "Token for retrieving the next page of results. Empty if there are no more pages.", + "type": "string", + "examples": [ + "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=" + ] + }, + "prev_page_token": { + "description": "Token for retrieving the previous page of results. Empty if this is the first page.", + "type": "string", + "examples": [ + "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9" + ] + }, + "total_size": { + "description": "Total number of users matching the request criteria, regardless of pagination.", + "type": "integer", + "format": "int64", + "examples": [ + 1042 + ] + }, + "users": { + "description": "List of matching users.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/usersUser" + } + } + } + }, + "passwordlessResendPasswordlessRequest": { + "type": "object", + "properties": { + "auth_request_id": { + "description": "The authentication request identifier from the original send passwordless email request. Use this to resend the Verification Code (OTP) or Magic Link to the same email address.", + "type": "string", + "examples": [ + "h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ" + ] + } + } + }, + "authpasswordlessPasswordlessType": { + "type": "string", + "enum": [ + "OTP", + "LINK", + "LINK_OTP" + ] + }, + "passwordlessSendPasswordlessResponse": { + "type": "object", + "properties": { + "auth_request_id": { + "description": "Unique identifier for this passwordless authentication request. Use this ID to resend emails.", + "type": "string", + "readOnly": true, + "examples": [ + "h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ" + ] + }, + "expires_at": { + "description": "Unix timestamp (seconds since epoch) when the passwordless authentication will expire. After this time, the OTP or magic link will no longer be valid.", + "type": "string", + "format": "int64", + "readOnly": true, + "examples": [ + 1748696575 + ] + }, + "expires_in": { + "description": "Number of seconds from now until the passwordless authentication expires. This is a convenience field calculated from the expires_at timestamp.", + "type": "integer", + "format": "int64", + "readOnly": true, + "examples": [ + 300 + ] + }, + "passwordless_type": { + "description": "Type of passwordless authentication that was sent via email. OTP sends a numeric code, LINK sends a clickable magic link, and LINK_OTP provides both options for user convenience.", + "$ref": "#/components/schemas/authpasswordlessPasswordlessType", + "examples": [ + "OTP" + ] + } + } + }, + "passwordlessTemplateType": { + "type": "string", + "enum": [ + "SIGNIN", + "SIGNUP" + ] + }, + "passwordlessSendPasswordlessRequest": { + "type": "object", + "properties": { + "email": { + "description": "Email address where the passwordless authentication credentials will be sent. Must be a valid email format.", + "type": "string", + "examples": [ + "john.doe@example.com" + ] + }, + "expires_in": { + "description": "Time in seconds until the passwordless authentication expires. If not specified, defaults to 300 seconds (5 minutes)", + "type": "integer", + "format": "int64", + "examples": [ + 300 + ] + }, + "magiclink_auth_uri": { + "description": "Your application's callback URL where users will be redirected after clicking the magic link in their email. The link token will be appended as a query parameter as link_token", + "type": "string", + "examples": [ + "https://yourapp.com/auth/passwordless/callback" + ] + }, + "state": { + "description": "Custom state parameter that will be returned unchanged in the verification response. Use this to maintain application state between the authentication request and callback, such as the intended destination after login", + "type": "string", + "examples": [ + "d62ivasry29lso" + ] + }, + "template": { + "description": "Specifies the authentication intent for the passwordless request. Use SIGNIN for existing users or SIGNUP for new user registration. This affects the email template and user experience flow.", + "$ref": "#/components/schemas/passwordlessTemplateType", + "examples": [ + "SIGNIN" + ] + }, + "template_variables": { + "description": "A set of key-value pairs to personalize the email template.\n\n* You may include up to 30 key-value pairs.\n* The following variable names are reserved by the system and cannot be supplied: `otp`, `expiry_time_relative`, `link`, `expire_time`, `expiry_time`.\n* Every variable referenced in your email template must be included as a key-value pair.\n\nUse these variables to insert custom information, such as a team name, URL or the user's employee ID. All variables are interpolated before the email is sent, regardless of the email provider.", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "examples": [ + { + "custom_variable_key": "custom_variable_value" + } + ] + } + } + }, + "passwordlessVerifyPasswordLessRequest": { + "type": "object", + "properties": { + "auth_request_id": { + "description": "The authentication request identifier returned from the send passwordless email endpoint. Required when verifying OTP codes to link the verification with the original request.", + "type": "string", + "examples": [ + "h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ" + ] + }, + "code": { + "description": "The Verification Code (OTP) received via email. This is typically a 6-digit numeric code that users enter manually to verify their identity.", + "type": "string", + "examples": [ + "123456" + ] + }, + "link_token": { + "description": "The unique token from the magic link URL received via email. Extract this token when users click the magic link and are redirected to your application to later verify the user.", + "type": "string", + "examples": [ + "afe9d61c-d80d-4020-a8ee-61765ab71cb3" + ] + } + } + }, + "passwordlessVerifyPasswordLessResponse": { + "type": "object", + "properties": { + "email": { + "description": "Email address of the successfully authenticated user. This confirms which email account was verified through the passwordless flow.", + "type": "string", + "readOnly": true, + "examples": [ + "john.doe@example.com" + ] + }, + "passwordless_type": { + "description": "The type of passwordless authentication that was successfully verified, confirming which method the user completed.", + "$ref": "#/components/schemas/authpasswordlessPasswordlessType", + "examples": [ + "OTP" + ] + }, + "state": { + "description": "The custom state parameter that was provided in the original authentication request, returned unchanged. Use this to restore your application's context after authentication.", + "type": "string", + "readOnly": true, + "examples": [ + "kdt7yiag28t341fr1" + ] + }, + "template": { + "description": "Specifies which email template to choose. For User Signin choose SIGNIN and for User Signup use SIGNUP", + "$ref": "#/components/schemas/passwordlessTemplateType", + "examples": [ + "SIGNIN" + ] + } + } + }, + "rolesPermission": { + "type": "object", + "title": "Permission Entity", + "properties": { + "create_time": { + "type": "string", + "format": "date-time" + }, + "description": { + "type": "string" + }, + "id": { + "type": "string" + }, + "is_scalekit_permission": { + "description": "Indicates whether this permission is predefined by Scalekit", + "type": "boolean", + "examples": [ + true + ] + }, + "name": { + "type": "string" + }, + "update_time": { + "type": "string", + "format": "date-time" + } + } + }, + "rolesListPermissionsResponse": { + "type": "object", + "properties": { + "next_page_token": { + "description": "Token to retrieve next page of results", + "type": "string", + "examples": [ + "token_def456" + ] + }, + "permissions": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/rolesPermission" + } + }, + "prev_page_token": { + "description": "Token to retrieve previous page of results", + "type": "string", + "examples": [ + "token_def456" + ] + }, + "total_size": { + "description": "Total number of permissions available", + "type": "integer", + "format": "int64", + "examples": [ + 150 + ] + } + } + }, + "v1rolesCreatePermission": { + "type": "object", + "properties": { + "description": { + "description": "Description of the permission", + "type": "string", + "examples": [ + "Allows user to read documents from the system" + ] + }, + "name": { + "description": "Unique name/ID of the permission", + "type": "string", + "examples": [ + "read:documents" + ] + } + } + }, + "rolesCreatePermissionResponse": { + "type": "object", + "properties": { + "permission": { + "$ref": "#/components/schemas/rolesPermission" + } + } + }, + "rolesGetPermissionResponse": { + "type": "object", + "properties": { + "permission": { + "$ref": "#/components/schemas/rolesPermission" + } + } + }, + "rolesUpdatePermissionResponse": { + "type": "object", + "properties": { + "permission": { + "$ref": "#/components/schemas/rolesPermission" + } + } + }, + "rolesListRolesResponse": { + "type": "object", + "properties": { + "roles": { + "description": "List of all roles in the environment with their metadata and optionally their permissions.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/v1rolesRole" + }, + "examples": [ + [ + { + "display_name": "Administrator", + "id": "role_1234abcd5678efgh", + "name": "admin" + }, + { + "display_name": "Viewer", + "id": "role_9876zyxw5432vuts", + "name": "viewer" + } + ] + ] + } + } + }, + "v1rolesCreateRole": { + "type": "object", + "properties": { + "description": { + "description": "Detailed description of the role's purpose, capabilities, and intended use cases. Maximum 2000 characters.", + "type": "string", + "examples": [ + "Can create, edit, and publish content but cannot delete content or manage user accounts" + ] + }, + "display_name": { + "description": "Human-readable display name for the role. Used in user interfaces, reports, and user-facing communications.", + "type": "string", + "examples": [ + "Content Editor" + ] + }, + "extends": { + "description": "Name of the base role that this role extends. Enables hierarchical role inheritance where this role inherits all permissions from the base role.", + "type": "string", + "examples": [ + "viewer" + ] + }, + "name": { + "description": "Unique name identifier for the role. Must be alphanumeric with underscores, 1-64 characters. This name is used in API calls and cannot be changed after creation.", + "type": "string", + "examples": [ + "content_editor" + ] + }, + "permissions": { + "description": "List of permission names to assign to this role. Permissions must exist in the current environment. Maximum 100 permissions per role.", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "read:content", + "write:content", + "publish:content" + ] + ] + } + } + }, + "rolesCreateRoleResponse": { + "type": "object", + "properties": { + "role": { + "description": "The created role object with system-generated ID and all configuration details.", + "$ref": "#/components/schemas/v1rolesRole", + "examples": [ + { + "description": "Can edit content", + "display_name": "Content Editor", + "id": "role_1234abcd5678efgh", + "name": "content_editor" + } + ] + } + } + }, + "rolesUpdateDefaultRole": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "description": "Unique name of the role", + "type": "string", + "examples": [ + "creator" + ] + } + } + }, + "rolesUpdateDefaultRolesRequest": { + "type": "object", + "properties": { + "default_creator": { + "description": "Default creator role (deprecated - use default_creator_role field instead)", + "$ref": "#/components/schemas/rolesUpdateDefaultRole", + "examples": [ + { + "description": "Role for creating resources", + "display_name": "Creator Role", + "id": "role_1234567890", + "name": "creator" + } + ] + }, + "default_creator_role": { + "description": "Name of the role to set as the default creator role. This role will be automatically assigned to users who create new resources in the environment. Must be a valid role name that exists in the environment.", + "type": "string", + "examples": [ + "creator" + ] + }, + "default_member": { + "description": "Default member role (deprecated - use default_member_role field instead)", + "$ref": "#/components/schemas/rolesUpdateDefaultRole", + "examples": [ + { + "description": "Role for regular members", + "display_name": "Member Role", + "id": "role_0987654321", + "name": "member" + } + ] + }, + "default_member_role": { + "description": "Name of the role to set as the default member role. This role will be automatically assigned to new users when they join the environment. Must be a valid role name that exists in the environment.", + "type": "string", + "examples": [ + "member" + ] + } + } + }, + "rolesUpdateDefaultRolesResponse": { + "type": "object", + "properties": { + "default_creator": { + "description": "The role that is now set as the default creator role for the environment. Contains complete role information including permissions and metadata.", + "$ref": "#/components/schemas/v1rolesRole", + "examples": [ + { + "description": "Role for creating resources", + "display_name": "Creator Role", + "id": "role_1234567890", + "name": "creator" + } + ] + }, + "default_member": { + "description": "The role that is now set as the default member role for the environment. Contains complete role information including permissions and metadata.", + "$ref": "#/components/schemas/v1rolesRole", + "examples": [ + { + "description": "Role for regular members", + "display_name": "Member Role", + "id": "role_0987654321", + "name": "member" + } + ] + } + } + }, + "rolesGetRoleResponse": { + "type": "object", + "properties": { + "role": { + "description": "The complete role object with all metadata, permissions, and inheritance details.", + "$ref": "#/components/schemas/v1rolesRole", + "examples": [ + { + "dependent_roles_count": 2, + "display_name": "Content Editor", + "id": "role_1234abcd5678efgh", + "name": "content_editor", + "permissions": [ + { + "name": "read:content" + } + ] + } + ] + } + } + }, + "rolesUpdateRoleResponse": { + "type": "object", + "properties": { + "role": { + "description": "The updated role object with all current configuration details.", + "$ref": "#/components/schemas/v1rolesRole", + "examples": [ + { + "description": "Can edit and approve content", + "display_name": "Senior Editor", + "id": "role_1234abcd5678efgh", + "name": "content_editor" + } + ] + } + } + }, + "rolesListDependentRolesResponse": { + "type": "object", + "properties": { + "roles": { + "description": "List of dependent roles", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/v1rolesRole" + } + } + } + }, + "rolesListRolePermissionsResponse": { + "type": "object", + "properties": { + "permissions": { + "description": "List of permissions directly assigned to the role", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/rolesPermission" + } + } + } + }, + "RolesServiceAddPermissionsToRoleBody": { + "type": "object", + "properties": { + "permission_names": { + "description": "List of permission names to add to the role", + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "rolesAddPermissionsToRoleResponse": { + "type": "object", + "properties": { + "permissions": { + "description": "List of all permissions belonging to the role after addition", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/rolesPermission" + } + } + } + }, + "rolesListEffectiveRolePermissionsResponse": { + "type": "object", + "properties": { + "permissions": { + "description": "List of all effective permissions including those inherited from base roles", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/rolesPermission" + } + } + } + }, + "rolesGetRoleUsersCountResponse": { + "type": "object", + "properties": { + "count": { + "description": "Number of users associated with the role", + "type": "string", + "format": "int64", + "examples": [ + 10 + ] + } + } + }, + "sessionsAuthenticatedClients": { + "description": "AuthenticatedClients represents an authenticated client in a session along with its organization context.", + "type": "object", + "properties": { + "client_id": { + "description": "Unique identifier of the authenticated client application.", + "type": "string", + "examples": [ + "skc_1234567890" + ] + }, + "organization_id": { + "description": "Active or last active Organization ID associated with the authenticated client.", + "type": "string", + "examples": [ + "org_1234567890" + ] + } + } + }, + "v1sessionsLocation": { + "type": "object", + "properties": { + "city": { + "description": "City name where the session originated based on IP geolocation. Approximate location derived from IP address.", + "type": "string", + "examples": [ + "San Francisco" + ] + }, + "latitude": { + "description": "Latitude coordinate of the estimated location. Decimal format (e.g., '37.7749'). Note: Represents IP geolocation center and may not be precise.", + "type": "string", + "examples": [ + "37.7749" + ] + }, + "longitude": { + "description": "Longitude coordinate of the estimated location. Decimal format (e.g., '-122.4194'). Note: Represents IP geolocation center and may not be precise.", + "type": "string", + "examples": [ + "-122.4194" + ] + }, + "region": { + "description": "Geographic region name derived from IP geolocation. Represents the country-level location (e.g., 'United States', 'France').", + "type": "string", + "examples": [ + "United States" + ] + }, + "region_subdivision": { + "description": "Regional subdivision code or name (e.g., state abbreviation for US, province for Canada). Two-letter ISO format when applicable.", + "type": "string", + "examples": [ + "CA" + ] + } + } + }, + "sessionsDeviceDetails": { + "type": "object", + "properties": { + "browser": { + "description": "Browser name and family extracted from the user agent. Examples: Chrome, Safari, Firefox, Edge, Mobile Safari.", + "type": "string", + "examples": [ + "Chrome" + ] + }, + "browser_version": { + "description": "Version of the browser application. Represents the specific release version of the browser being used.", + "type": "string", + "examples": [ + "120.0.0.0" + ] + }, + "device_type": { + "description": "Categorized device type classification. Possible values: 'desktop' (traditional computers), 'mobile' (smartphones and small tablets), 'tablet' (large tablets), 'other'. Useful for displaying session information by device category.", + "type": "string", + "examples": [ + "desktop" + ] + }, + "ip": { + "description": "IP address of the device that initiated the session. This is the public-facing IP address used to connect to the application. Useful for security audits and geographic distribution analysis.", + "type": "string", + "examples": [ + "192.0.2.1" + ] + }, + "location": { + "description": "Geographic location information derived from IP address geolocation. Includes country, region, city, and coordinates. Note: Based on IP location data and may not represent the user's exact physical location.", + "$ref": "#/components/schemas/v1sessionsLocation" + }, + "os": { + "description": "Operating system name extracted from the user agent and device headers. Examples: macOS, Windows, Linux, iOS, Android.", + "type": "string", + "examples": [ + "macOS" + ] + }, + "os_version": { + "description": "Version of the operating system. Represents the specific OS release the device is running.", + "type": "string", + "examples": [ + "14.2" + ] + }, + "user_agent": { + "description": "Complete HTTP User-Agent header string from the client request. Contains browser type, version, and operating system information. Used for detailed device fingerprinting and user agent analysis.", + "type": "string", + "examples": [ + "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" + ] + } + } + }, + "sessionsSessionDetails": { + "type": "object", + "properties": { + "absolute_expires_at": { + "description": "Hard expiration timestamp for the session regardless of user activity. The session will be forcibly terminated at this time. This represents the maximum session lifetime from creation.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-01-22T10:30:00Z" + ] + }, + "authenticated_clients": { + "description": "Details of the authenticated clients for this session: client ID and organization context.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/sessionsAuthenticatedClients" + } + }, + "authenticated_organizations": { + "description": "List of organization IDs that have been authenticated for this user within the current session. Contains all organizations where the user has successfully completed SSO or authentication.", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "org_123", + "org_456" + ] + ] + }, + "created_at": { + "description": "Timestamp indicating when the session was created. This is set once at session creation and remains constant throughout the session lifetime.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-01-15T10:30:00Z" + ] + }, + "device": { + "description": "Complete device metadata associated with this session including browser, operating system, device type, and geographic location based on IP address.", + "$ref": "#/components/schemas/sessionsDeviceDetails" + }, + "expired_at": { + "description": "Timestamp when the session was terminated. Null if the session is still active. Set when the session expires due to reaching idle_expires_at or absolute_expires_at timeout, or when administratively revoked. Not set for user-initiated logout (see logout_at instead).", + "type": "string", + "format": "date-time", + "examples": [ + "2025-01-15T12:00:00Z" + ] + }, + "idle_expires_at": { + "description": "Projected expiration timestamp if the session remains idle without user activity. This timestamp is recalculated with each user activity. Session will be automatically terminated at this time if no activity occurs.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-01-15T11:30:00Z" + ] + }, + "last_active_at": { + "description": "Timestamp of the most recent user activity detected in this session. Updated on each API request or user interaction. Used to determine if a session has exceeded the idle timeout threshold.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-01-15T10:55:30Z" + ] + }, + "logout_at": { + "description": "Timestamp when the user explicitly logged out from the session. Null if the user has not logged out. When set, indicates the session ended due to explicit user logout rather than timeout.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-01-15T14:00:00Z" + ] + }, + "organization_id": { + "description": "Organization ID for the user's most recently active organization within this session. This represents the primary organization context for the current session.", + "type": "string", + "examples": [ + "org_1234567890123456" + ] + }, + "session_id": { + "description": "Unique identifier for the session. System-generated read-only field used to reference this session.", + "type": "string", + "examples": [ + "ses_1234567890123456" + ] + }, + "status": { + "description": "Current operational status of the session. Possible values: 'active' (session is valid and requests are allowed), 'expired' (session terminated due to idle or absolute timeout), 'revoked' (session was administratively revoked), 'logout' (user explicitly logged out). Use this to determine if the session can be used for new requests.", + "type": "string", + "examples": [ + "active" + ] + }, + "updated_at": { + "description": "Timestamp indicating when the session was last updated. Updated whenever session state changes such as organization context changes or metadata updates.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-01-15T10:45:00Z" + ] + }, + "user_id": { + "description": "Unique identifier for the user who owns and is authenticated within this session.", + "type": "string", + "examples": [ + "usr_1234567890123456" + ] + } + } + }, + "sessionsRevokedSessionDetails": { + "type": "object", + "properties": { + "absolute_expires_at": { + "description": "The absolute expiration timestamp that was configured for this session before revocation. Represents the hard deadline regardless of activity.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-01-22T10:30:00Z" + ] + }, + "created_at": { + "description": "Timestamp indicating when the session was originally created before revocation.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-01-15T10:30:00Z" + ] + }, + "expired_at": { + "description": "Timestamp when the session was actually terminated. Set to the revocation time when the session is revoked.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-01-15T12:00:00Z" + ] + }, + "idle_expires_at": { + "description": "The idle expiration timestamp that was configured for this session before revocation. Represents when the session would have expired due to inactivity.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-01-15T11:30:00Z" + ] + }, + "last_active_at": { + "description": "Timestamp of the last recorded user activity in this session before revocation. Helps identify inactive sessions that were revoked.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-01-15T10:55:30Z" + ] + }, + "logout_at": { + "description": "Timestamp when the user explicitly logged out (if applicable). Null if the session was revoked without prior logout.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-01-15T14:00:00Z" + ] + }, + "session_id": { + "description": "Unique identifier for the revoked session. System-generated read-only field.", + "type": "string", + "examples": [ + "ses_1234567890123456" + ] + }, + "status": { + "description": "Status of the session after revocation. Always 'revoked' since only active sessions can be revoked. Sessions that were already expired or logged out are not included in the revocation response.", + "type": "string", + "examples": [ + "revoked" + ] + }, + "updated_at": { + "description": "Timestamp indicating when the session was last modified before revocation.", + "type": "string", + "format": "date-time", + "examples": [ + "2025-01-15T10:45:00Z" + ] + }, + "user_id": { + "description": "Unique identifier for the user who owned this session.", + "type": "string", + "examples": [ + "usr_1234567890123456" + ] + } + } + }, + "sessionsRevokeSessionResponse": { + "type": "object", + "properties": { + "revoked_session": { + "description": "Details of the revoked session including session ID, user ID, creation and revocation timestamps, and final device information.", + "$ref": "#/components/schemas/sessionsRevokedSessionDetails" + } + } + }, + "usersListUsersResponse": { + "type": "object", + "properties": { + "next_page_token": { + "description": "Token for retrieving the next page of results. Empty if there are no more pages.", + "type": "string", + "examples": [ + "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=" + ] + }, + "prev_page_token": { + "description": "Token for retrieving the previous page of results. Empty if this is the first page.", + "type": "string", + "examples": [ + "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9" + ] + }, + "total_size": { + "description": "Total number of users matching the request criteria, regardless of pagination.", + "type": "integer", + "format": "int64", + "examples": [ + 1042 + ] + }, + "users": { + "description": "List of users.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/usersUser" + } + } + } + }, + "usersGetUserResponse": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/usersUser" + } + } + }, + "usersUpdateUserProfile": { + "type": "object", + "properties": { + "custom_attributes": { + "description": "Updates custom attributes for extended user profile data and application-specific information. Use this field to store business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs.", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "examples": [ + { + "department": "engineering", + "security_clearance": "level2" + } + ] + }, + "family_name": { + "description": "Updates the user's family name (last name or surname). Use this field to modify how the user's last name appears throughout the system. Maximum 255 characters allowed.", + "type": "string", + "examples": [ + "Doe" + ] + }, + "first_name": { + "description": "[DEPRECATED] Use given_name instead. User's given name. Maximum 200 characters.", + "type": "string", + "examples": [ + "John" + ] + }, + "gender": { + "description": "Updates the user's gender identity information. Use this field to store the user's gender identity for personalization, compliance, or reporting purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies.", + "type": "string", + "examples": [ + "male" + ] + }, + "given_name": { + "description": "Updates the user's given name (first name). Use this field to modify how the user's first name appears in the system and user interfaces. Maximum 255 characters allowed.", + "type": "string", + "examples": [ + "John" + ] + }, + "groups": { + "description": "Updates the list of group names the user belongs to within the organization. Use this field to manage the user's group memberships for role-based access control, team assignments, or organizational structure. Groups are typically used for permission management and collaborative access. Each group name must be unique within the list, 1-250 characters long, with a maximum of 50 groups per user.", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "engineering", + "managers" + ] + ] + }, + "last_name": { + "description": "[DEPRECATED] Use family_name instead. User's family name. Maximum 200 characters.", + "type": "string", + "examples": [ + "Doe" + ] + }, + "locale": { + "description": "Updates the user's preferred language and region settings using BCP-47 format codes. Use this field to customize the user's experience with localized content, date formats, number formatting, and UI language. When not specified, the user inherits the organization's default locale settings. Common values include `en-US`, `en-GB`, `fr-FR`, `de-DE`, and `es-ES`.", + "type": "string", + "examples": [ + "en-US" + ] + }, + "metadata": { + "description": "Updates system-managed key-value pairs for internal tracking and operational data. Use this field to store system-generated metadata like account status, signup source, last activity tracking, or integration-specific identifiers. These fields are typically managed by automated processes rather than direct user input. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs.", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "examples": [ + { + "account_status": "active", + "signup_source": "mobile_app" + } + ] + }, + "name": { + "description": "Updates the user's complete display name. Use this field when you want to set the full name as a single string rather than using separate given and family names. This name appears in user interfaces, reports, and anywhere a formatted display name is needed.", + "type": "string", + "examples": [ + "John Doe" + ] + }, + "phone_number": { + "description": "Updates the user's phone number in E.164 international format. Use this field to enable SMS-based authentication methods, two-factor authentication, or phone-based account recovery. The phone number must include the country code and be formatted according to E.164 standards (e.g., `+1` for US numbers). This field is required when enabling SMS authentication features.", + "type": "string", + "examples": [ + "+14155552671" + ] + }, + "picture": { + "description": "Updates the URL to the user's profile picture or avatar image. Use this field to set or change the user's profile photo that appears in user interfaces, directory listings, and collaborative features. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. Maximum URL length is 2048 characters.", + "type": "string", + "examples": [ + "https://example.com/avatar.jpg" + ] + }, + "preferred_username": { + "description": "Updates the user's preferred username for display and identification purposes. Use this field to set a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, and informal communications. Maximum 512 characters allowed.", + "type": "string", + "examples": [ + "John Michael Doe" + ] + } + } + }, + "v1usersUpdateUser": { + "type": "object", + "properties": { + "external_id": { + "description": "Your application's unique identifier for this organization, used to link Scalekit with your system.", + "type": "string", + "examples": [ + "ext_12345a67b89c" + ] + }, + "metadata": { + "description": "Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars).", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "examples": [ + { + "department": "engineering", + "location": "nyc-office" + } + ] + }, + "user_profile": { + "description": "User's personal information including name, address, and other profile attributes.", + "$ref": "#/components/schemas/usersUpdateUserProfile" + } + } + }, + "usersUpdateUserResponse": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/usersUser" + } + } + }, + "sessionsUserSessionDetails": { + "type": "object", + "properties": { + "next_page_token": { + "description": "Pagination token for retrieving the next page of results. Empty string if there are no more pages (you have reached the final page of results).", + "type": "string", + "examples": [ + "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAic2VzXzEyMzQ1In0=" + ] + }, + "prev_page_token": { + "description": "Pagination token for retrieving the previous page of results. Empty string for the first page. Use this to navigate backward through result pages.", + "type": "string", + "examples": [ + "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInNlc183OTAxIn0=" + ] + }, + "sessions": { + "description": "Array of session objects for the requested user. May contain fewer entries than the requested page_size when reaching the final page of results.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/sessionsSessionDetails" + } + }, + "total_size": { + "description": "Total number of sessions matching the applied filter criteria, regardless of pagination. This represents the complete result set size before pagination is applied.", + "type": "integer", + "format": "int64", + "examples": [ + 42 + ] + } + } + }, + "sessionsRevokeAllUserSessionsResponse": { + "type": "object", + "properties": { + "revoked_sessions": { + "description": "List of all sessions that were revoked, including detailed information for each revoked session with IDs, timestamps, and device details.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/sessionsRevokedSessionDetails" + } + }, + "total_revoked": { + "description": "Total count of active sessions that were revoked. Useful for confirmation and audit logging.", + "type": "integer", + "format": "int64", + "examples": [ + 5 + ] + } + } + }, + "usersSearchUsersResponse": { + "type": "object", + "properties": { + "next_page_token": { + "description": "Token for retrieving the next page of results. Empty if there are no more pages.", + "type": "string", + "examples": [ + "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=" + ] + }, + "prev_page_token": { + "description": "Token for retrieving the previous page of results. Empty if this is the first page.", + "type": "string", + "examples": [ + "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9" + ] + }, + "total_size": { + "description": "Total number of users matching the request criteria, regardless of pagination.", + "type": "integer", + "format": "int64", + "examples": [ + 1042 + ] + }, + "users": { + "description": "List of matching users.", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/usersUser" + } + } + } + }, + "webauthnAllAcceptedCredentialsOptions": { + "type": "object", + "properties": { + "all_accepted_credential_ids": { + "description": "List of credential IDs the user can authenticate with", + "type": "array", + "items": { + "type": "string" + } + }, + "rp_id": { + "description": "Relying Party ID for credential operations", + "type": "string", + "examples": [ + "example.com" + ] + }, + "user_id": { + "description": "User ID for credential verification", + "type": "string", + "examples": [ + "user_xyz789" + ] + } + } + }, + "WebAuthnCredentialAuthenticator": { + "type": "object", + "properties": { + "aaguid": { + "description": "Authenticator Attestation GUID (AAGUID) identifying the device model", + "type": "string" + }, + "attachment": { + "description": "Attachment type: \"platform\" (built-in) or \"cross-platform\"", + "type": "string", + "examples": [ + "platform" + ] + }, + "icon_dark": { + "description": "Icon URL for dark theme display", + "type": "string" + }, + "icon_light": { + "description": "Icon URL for light theme display", + "type": "string" + }, + "name": { + "description": "Human-readable name of the authenticator model", + "type": "string", + "examples": [ + "Apple Touch ID" + ] + } + } + }, + "WebAuthnCredentialAuthenticatorFlags": { + "type": "object", + "properties": { + "backup_eligible": { + "description": "Whether this credential can be backed up to another device", + "type": "boolean" + }, + "backup_state": { + "description": "Whether this credential was synced or backed up", + "type": "boolean" + }, + "user_present": { + "description": "Whether the user was present during authentication", + "type": "boolean" + }, + "user_verified": { + "description": "Whether the user was verified (e.g., fingerprint, PIN)", + "type": "boolean" + } + } + }, + "WebAuthnCredentialClientInfo": { + "type": "object", + "properties": { + "city": { + "description": "City name", + "type": "string", + "examples": [ + "San Francisco" + ] + }, + "ip": { + "description": "IP address from which credential was registered", + "type": "string", + "examples": [ + "192.0.2.1" + ] + }, + "region": { + "description": "Geographic region (e.g., \"US\")", + "type": "string", + "examples": [ + "US" + ] + }, + "region_subdivision": { + "description": "Regional subdivision (e.g., \"CA\")", + "type": "string", + "examples": [ + "CA" + ] + } + } + }, + "WebAuthnCredentialUserAgent": { + "type": "object", + "properties": { + "browser": { + "description": "Browser name (e.g., \"Chrome\", \"Safari\")", + "type": "string", + "examples": [ + "Chrome" + ] + }, + "browser_version": { + "description": "Browser version number", + "type": "string", + "examples": [ + "120.0.6099.129" + ] + }, + "device_model": { + "description": "Device model if available", + "type": "string", + "examples": [ + "iPhone15,2" + ] + }, + "device_type": { + "description": "Device type: \"desktop\", \"mobile\", or \"tablet\"", + "type": "string", + "examples": [ + "mobile" + ] + }, + "os": { + "description": "Operating system name (e.g., \"Windows\", \"iOS\")", + "type": "string", + "examples": [ + "macOS" + ] + }, + "os_version": { + "description": "Operating system version", + "type": "string", + "examples": [ + "14.2" + ] + }, + "raw": { + "description": "Raw user agent string from the browser", + "type": "string" + }, + "url": { + "description": "Parsed user agent URL reference", + "type": "string" + } + } + }, + "webauthnWebAuthnCredential": { + "type": "object", + "properties": { + "attestation_type": { + "description": "Type of attestation: \"none\", \"indirect\", or \"direct\"", + "type": "string", + "examples": [ + "direct" + ] + }, + "authenticator": { + "description": "Authenticator information including model and name", + "$ref": "#/components/schemas/WebAuthnCredentialAuthenticator" + }, + "authenticator_flags": { + "description": "Flags indicating authenticator capabilities", + "$ref": "#/components/schemas/WebAuthnCredentialAuthenticatorFlags" + }, + "client_info": { + "description": "Geographic and network information from registration", + "$ref": "#/components/schemas/WebAuthnCredentialClientInfo" + }, + "created_at": { + "description": "Timestamp when the credential was created", + "type": "string", + "format": "date-time", + "examples": [ + "2025-02-15T06:23:44.560000Z" + ] + }, + "credential_id": { + "description": "The actual credential ID bytes from the authenticator", + "type": "string", + "contentEncoding": "base64" + }, + "display_name": { + "description": "Optional user-friendly name for this passkey", + "type": "string", + "examples": [ + "My Yubikey" + ] + }, + "id": { + "description": "Credential unique identifier", + "type": "string", + "examples": [ + "cred_abc123" + ] + }, + "transports": { + "description": "Supported transports for this credential", + "type": "array", + "items": { + "type": "string" + } + }, + "updated_at": { + "description": "Timestamp of last update", + "type": "string", + "format": "date-time", + "examples": [ + "2025-02-15T06:23:44.560000Z" + ] + }, + "user_agent": { + "description": "Browser and device information from registration", + "$ref": "#/components/schemas/WebAuthnCredentialUserAgent" + }, + "user_id": { + "description": "User ID this credential belongs to", + "type": "string", + "examples": [ + "user_xyz789" + ] + } + } + }, + "webauthnListCredentialsResponse": { + "type": "object", + "properties": { + "all_accepted_credentials_options": { + "description": "Options including RP ID and all accepted credential IDs for authentication", + "$ref": "#/components/schemas/webauthnAllAcceptedCredentialsOptions" + }, + "credentials": { + "description": "All passkeys registered for the user", + "type": "array", + "items": { + "type": "object", + "$ref": "#/components/schemas/webauthnWebAuthnCredential" + } + } + } + }, + "webauthnUnknownCredentialOptions": { + "type": "object", + "properties": { + "credential_id": { + "description": "The deleted credential ID", + "type": "string", + "examples": [ + "cred_abc123" + ] + }, + "rp_id": { + "description": "The RP ID for this credential", + "type": "string", + "examples": [ + "example.com" + ] + } + } + }, + "webauthnDeleteCredentialResponse": { + "type": "object", + "properties": { + "success": { + "description": "Whether the credential was successfully deleted", + "type": "boolean", + "examples": [ + true + ] + }, + "unknown_credential_options": { + "description": "Options for handling unknown credentials in client applications", + "$ref": "#/components/schemas/webauthnUnknownCredentialOptions" + } + } + }, + "WebAuthnServiceUpdateCredentialBody": { + "type": "object", + "properties": { + "display_name": { + "description": "Human-friendly name for this credential (1-120 characters)", + "type": "string", + "examples": [ + "My iPhone 15 Pro" + ] + } + } + }, + "webauthnUpdateCredentialResponse": { + "type": "object", + "properties": { + "credential": { + "description": "The updated credential with new display name", + "$ref": "#/components/schemas/webauthnWebAuthnCredential" + } + } + }, + "ScalekitEvent": { + "type": "object", + "required": [ + "spec_version", + "id", + "type", + "occurred_at", + "environment_id", + "object" + ], + "properties": { + "spec_version": { + "type": "string", + "example": "1", + "description": "The webhook specification version", + "pattern": "^[0-9]+$" + }, + "id": { + "type": "string", + "pattern": "^evt_", + "example": "evt_1234567890abcdef", + "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")", + "minLength": 1, + "maxLength": 32 + }, + "type": { + "type": "string", + "example": "organization.created", + "description": "The event type", + "enum": [ + "organization.created", + "organization.updated", + "organization.deleted", + "organization.sso_created", + "organization.sso_deleted", + "organization.sso_enabled", + "organization.sso_disabled", + "user.signup", + "user.login", + "user.logout", + "user.organization_invitation", + "user.organization_membership_created", + "user.organization_membership_updated", + "user.organization_membership_deleted", + "organization.directory.user_created", + "organization.directory.user_updated", + "organization.directory.user_deleted", + "organization.directory.group_created", + "organization.directory.group_updated", + "organization.directory.group_deleted", + "organization.directory_enabled", + "organization.directory_disabled", + "role.created", + "role.updated", + "role.deleted", + "permission.created", + "permission.updated", + "permission.deleted" + ] + }, + "occurred_at": { + "type": "string", + "format": "date-time", + "description": "When the event occurred (ISO 8601 format)", + "example": "2024-01-01T00:00:00Z" + }, + "environment_id": { + "type": "string", + "pattern": "^env_", + "example": "env_1234567890abcdef", + "description": "The environment ID where the event occurred", + "minLength": 1, + "maxLength": 32 + }, + "organization_id": { + "type": "string", + "pattern": "^org_", + "example": "org_1234567890abcdef", + "description": "The organization ID (if applicable)", + "minLength": 1, + "maxLength": 32 + }, + "object": { + "type": "string", + "description": "The type of object that triggered the webhook", + "enum": [ + "Organization", + "Connection", + "Role", + "Directory", + "DirectoryUser", + "DirectoryGroup", + "Permission", + "OrgMembership", + "User" + ], + "example": "Organization" + }, + "data": { + "type": "object", + "description": "The event payload (structure varies by event type)", + "additionalProperties": true, + "example": { + "id": "org_1234567890abcdef", + "name": "Example Organization", + "created_at": "2024-01-01T00:00:00Z" + } + }, + "display_name": { + "type": "string", + "description": "Human-readable display name for the event", + "example": "Organization Created", + "minLength": 1, + "maxLength": 200 + } + } + } + } + }, + "x-scalar-environments": { + "production": { + "variables": { + "SCALEKIT_ENVIRONMENT_URL": { + "default": "https://$SCALEKIT_ENVIRONMENT_URL", + "description": "yourapp.scalekit.com" + } + } + }, + "staging": { + "variables": { + "SCALEKIT_ENVIRONMENT_URL": { + "default": "https://$SCALEKIT_ENVIRONMENT_URL", + "description": "yourapp.scalekit.dev" + } + } + } + }, + "x-scalar-active-environment": "staging" +} \ No newline at end of file diff --git a/public/api/saaskit.scalar.yaml b/public/api/saaskit.scalar.yaml new file mode 100644 index 000000000..a6487ec1b --- /dev/null +++ b/public/api/saaskit.scalar.yaml @@ -0,0 +1,9584 @@ +openapi: 3.1.1 +info: + description: "# Overview\n\nThe Scalekit API is a RESTful API that enables you to manage organizations, users, and authentication settings. All requests must use HTTPS.\nAll API requests use the following base URLs:\n\n```\nhttps://{your-subdomain}.scalekit.dev (Development)\nhttps://{your-subdomain}.scalekit.com (Production)\nhttps://auth.yourapp.com (Custom domain)\n```\n\nScalekit operates two separate environments: Development and Production. Resources cannot be moved between environments.\n\n## Quickstart\n\nThe Scalekit API uses OAuth 2.0 Client Credentials for authentication.\n\nCopy your API credentials from the Scalekit dashboard's API Config section and set them as environment variables.\n\n```sh\nSCALEKIT_ENVIRONMENT_URL=''\nSCALEKIT_CLIENT_ID=''\nSCALEKIT_CLIENT_SECRET=''\n```\n\nGetting an access token\n\n1. Get your credentials from the [Scalekit Dashboard](https://app.scalekit.com)\n2. Request an access token:\n\n```sh\ncurl https:///oauth/token \\\n -X POST \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d 'client_id={client_id}' \\\n -d 'client_secret={client_secret}' \\\n -d 'grant_type=client_credentials'\n```\n\n3. Use the access token in API requests:\n\n```sh\ncurl https:///api/v1/organizations \\\n -H 'Content-Type: application/json' \\\n -H 'Authorization: Bearer {access_token}'\n```\n\nThe response includes an access token:\n\n```json\n{\n\t\"access_token\": \"eyJhbGciOiJSUzI1NiIsImtpZCI6InNua181Ok4OTEyMjU2NiIsInR5cCI6IkpXVCJ9...\",\n\t\"token_type\": \"Bearer\",\n\t\"expires_in\": 86399,\n\t\"scope\": \"openid\"\n}\n```\n\n## SDKs\n\nScalekit provides official SDKs for multiple programming languages. Check the changelog at GitHub repositories for the latest updates.\n\n### Node.js\n\n```sh\nnpm install @scalekit-sdk/node\n```\n\nCreate a new Scalekit client instance after initializing the environment variables\n\n```js\nimport { Scalekit } from \"@scalekit-sdk/node\";\n\nexport let scalekit = new Scalekit(\n\tprocess.env.SCALEKIT_ENVIRONMENT_URL,\n\tprocess.env.SCALEKIT_CLIENT_ID,\n\tprocess.env.SCALEKIT_CLIENT_SECRET\n);\n```\n\n[See the Node SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-node/releases)\n\n### Python\n\n```sh\npip install scalekit-sdk-python\n```\n\nCreate a new Scalekit client instance after initializing the environment variables.\n\n```py\nfrom scalekit import ScalekitClient\nimport os\n\nscalekit_client = ScalekitClient(\n os.environ.get('SCALEKIT_ENVIRONMENT_URL'),\n os.environ.get('SCALEKIT_CLIENT_ID'),\n os.environ.get('SCALEKIT_CLIENT_SECRET')\n)\n```\n\n[See the Python SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-python/releases)\n\n### Go\n\n```sh\ngo get -u github.com/scalekit-inc/scalekit-sdk-go\n```\n\nCreate a new Scalekit client instance after initializing the environment variables.\n\n```go\npackage main\n\nimport (\n \"os\"\n \"github.com/scalekit-inc/scalekit-sdk-go\"\n)\n\nscalekitClient := scalekit.NewScalekitClient(\n os.Getenv(\"SCALEKIT_ENVIRONMENT_URL\"),\n os.Getenv(\"SCALEKIT_CLIENT_ID\"),\n os.Getenv(\"SCALEKIT_CLIENT_SECRET\"),\n)\n```\n\n[See the Go SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-go/releases)\n\n### Java\n\n```gradle\n/* Gradle users - add the following to your dependencies in build file */\nimplementation \"com.scalekit:scalekit-sdk-java:2.0.11\"\n```\n\n```xml\n\n\n com.scalekit\n scalekit-sdk-java\n 2.0.11\n\n```\n\n[See the Java SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-java/releases)\n\n### Error handling\n\nThe API uses standard HTTP status codes:\n\n| Code | Description |\n| ----------- | -------------------- |\n| 200/201 | Success |\n| 400 | Invalid request |\n| 401 | Authentication error |\n| 404 | Resource not found |\n| 429 | Rate limit exceeded |\n| 500/501/504 | Server error |\n\nError responses include detailed information:\n\n```json\n{\n\t\"code\": 16,\n\t\"message\": \"Token empty\",\n\t\"details\": [\n\t\t{\n\t\t\t\"@type\": \"type.googleapis.com/scalekit.v1.errdetails.ErrorInfo\",\n\t\t\t\"error_code\": \"UNAUTHENTICATED\"\n\t\t}\n\t]\n}\n```\n\n---\n\nBuilding AI agents that need OAuth tokens, tool execution, or connected accounts? See the [AgentKit API reference](https://docs.scalekit.com/agentkit/apis/). For the complete endpoint list across both products, see [All APIs](https://docs.scalekit.com/apis/).\n" + title: SaaSKit APIs + contact: + name: Scalekit Inc + url: https://scalekit.com + email: support@scalekit.com + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0 + version: 1.0.0 + x-scalar-sdk-installation: + - lang: shell + description: Set up OAuth 2.0 Client Credentials authentication to access Scalekit APIs. Includes credential configuration, token exchange, and authenticated API request examples. + source: | + + # 1. Obtain API Credentials + # Get your credentials from the Scalekit dashboard + export SCALEKIT_ENVIRONMENT_URL="https://your-org.scalekit.dev" # Your Scalekit environment URL + export SCALEKIT_CLIENT_ID="your_client_id" # Your client ID + export SCALEKIT_CLIENT_SECRET="your_client_secret" # Your client secret + + # 2. Exchange client credentials an OAuth 2.0 access token + TOKEN_RESPONSE=$(curl -s -X POST "${SCALEKIT_ENVIRONMENT_URL}/oauth/token" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "client_id=${SCALEKIT_CLIENT_ID}" \ + -d "client_secret=${SCALEKIT_CLIENT_SECRET}" \ + -d "grant_type=client_credentials") + + # 3. Make Authenticated API Requests + curl -X GET "${SCALEKIT_ENVIRONMENT_URL}/api/v1/organizations" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${ACCESS_TOKEN}" \ + -H "Accept: application/json" +servers: + - url: https://$SCALEKIT_ENVIRONMENT_URL +security: + - oauth2: [] +tags: + - description: | + Organization represents a customer or a tenant of your product. This is the top level entity and all resources are mapped to this Organization object. Each organization is uniquely identified by `organization_id`. + + + name: Organizations + - description: Permission management for defining and controlling access to system resources. Create, retrieve, update, and delete granular permissions that represent specific actions users can perform. Permissions are the building blocks of role-based access control (RBAC) and can be assigned to roles to grant users the ability to perform specific operations. Use this service to define custom permissions for your application's unique access control requirements. + name: Permissions + - description: Comprehensive user management operations including user lifecycle, organization memberships, and invitation workflows. This service provides endpoints for creating, retrieving, updating, and deleting user accounts across your Scalekit environment. It supports both individual user operations and bulk operations for user administration, including user search, pagination, and metadata management. The service also handles user invitations and organization membership management. + name: Users + - description: Manage enterprise connections for your Scalekit environment. This service provides endpoints for retrieving, and updating connections. + name: Connections + - description: Directory management for viewing and controlling external identity provider connections in your Scalekit environment. This service provides endpoints for retrieving directory information, listing directories and their contents, and enabling or disabling directory synchronization. + name: Directory + - description: Role-based access control (RBAC) for defining and managing permissions in an environment. Create and update custom roles with explicit permissions, model role hierarchies through inheritance, view dependent roles, manage role-permission assignments, and list roles and permissions. Also provides a utility to count users assigned to a role. + name: Roles + - description: Comprehensive session management for user authentication and authorization. This service provides endpoints for retrieving session details, managing user sessions across devices, revoking individual sessions, and terminating all active sessions for a user. It supports session auditing, device tracking, and security monitoring with detailed session metadata including device information, IP geolocation, and activity timestamps. + name: Sessions + - description: | + Manage organization-level domains. Scalekit supports two domain types: + + - ORGANIZATION_DOMAIN: Used for SSO domain discovery. When a user signs in with a matching email domain, Scalekit routes them to the organization’s SSO provider and enforces SSO. + - ALLOWED_EMAIL_DOMAIN: Used to mark trusted email domains for an organization. When a user signs in or signs up with a matching domain, Scalekit suggests the organization in the organization switcher (authentication-method agnostic). + name: Domains + - description: Endpoints for managing API client applications. API clients enable secure, automated interactions between software systems without human intervention. Each client is uniquely identified by a `client_id` and can be configured with authentication settings, redirect URIs, and security parameters. Use these endpoints to create, manage, and configure API clients for your API clients. + name: API Auth + externalDocs: + url: https://docs.scalekit.com/m2m/overview + - description: Endpoints for sending and verifying passwordless authentication emails. These APIs allow users to authenticate without passwords by receiving a verification code or magic link in their email. + name: Magic link & OTP + - description: Endpoints for passkey-based authentication using WebAuthn/FIDO2 standards. + name: Passkeys +externalDocs: + description: Scalekit Docs + url: https://docs.scalekit.com/ +paths: + /api/v1/connections: + get: + description: Retrieves a list of connections in the environment + tags: + - Connections + summary: List connections + operationId: ConnectionService_ListConnections + parameters: + - schema: + type: string + description: Filter connections by organization identifier + name: organization_id + in: query + - schema: + type: string + description: Filter connections by email domain associated with the organization + name: domain + in: query + - schema: + type: string + description: Filter connections by status. Use 'all' to include all connections regardless of status. Default behavior shows only active (completed and enabled) connections + name: include + in: query + responses: + '200': + description: Successfully retrieved connections + content: + application/json: + schema: + $ref: '#/components/schemas/connectionsListConnectionsResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + // List connections by organization id + const connections = await scalekit.connection.listConnections(organizationId); + + // List connections by domain + const connections = await scalekit.connection.listConnectionsByDomain(domain); + - label: Python SDK + lang: python + source: |- + # List connections by organization id + connections = scalekit_client.connection.list_connections( + organization_id + ) + + # List connections by domain + response = scalekit_client.connection.list_connections_by_domain(domain="example.com") + - label: Go SDK + lang: go + source: |- + // List connections by organization id + connections, err := scalekitClient.Connection().ListConnections( + ctx, + organizationId + ) + + // List connections by domain + connections, err := scalekitClient.Connection().ListConnectionsByDomain(ctx, + domain) + - label: Java SDK + lang: java + source: |- + // List connections by organization id + ListConnectionsResponse response = scalekitClient.connections( + ).listConnections(organizationId); + + // List connections by domain + ListConnectionsResponse response = scalekitClient.connections( + ).listConnectionsByDomain("your-domain.com"); + /api/v1/invites/organizations/{organization_id}/users/{id}/resend: + patch: + description: Resends an invitation email to a user who has a pending or expired invitation in the specified organization. If the invitation has expired, a new invitation will be automatically created and sent. If the invitation is still valid, a reminder email will be sent instead. Use this endpoint when a user hasn't responded to their initial invitation and you need to send them a reminder or when the original invitation has expired. The invitation email includes a secure magic link that allows the user to complete their account setup and join the organization. Each resend operation increments the resent counter. + tags: + - Users + summary: Resend user invitation email + operationId: UserService_ResendInvite + parameters: + - schema: + type: string + description: Unique identifier of the organization containing the pending invitation. Must start with 'org_' and be 1-32 characters long. + name: organization_id + in: path + required: true + - schema: + type: string + description: System-generated user ID of the user who has a pending invitation. Must start with 'usr_' and be 19-25 characters long. + name: id + in: path + required: true + responses: + '200': + description: Successfully resent the invitation email. Returns the updated invitation object with organization ID, user ID, membership status, timestamps, and resent count. If expired, a new invitation is created; otherwise, the existing one is resent. + content: + application/json: + schema: + $ref: '#/components/schemas/usersResendInviteResponse' + '400': + description: Invalid request — common causes include user ID or organization ID is invalid, full-stack authentication is disabled, user profile is missing, invite already accepted, or missing expiry time in user management settings. + content: + application/json: + schema: + $ref: '#/components/schemas/errdetailsErrorInfo' + '404': + description: Resource not found — the specified user, organization, membership, or invitation could not be found in the specified environment. Verify that all IDs are correct and that the resources exist before attempting to resend an invitation. + content: + application/json: + schema: + $ref: '#/components/schemas/errdetailsErrorInfo' + '500': + description: Internal server error — an unexpected error occurred while processing the invitation resend request. This may be due to database connectivity issues, problems generating the secure magic link, email delivery service failures, or transaction errors during invitation processing. Contact support if the problem persists. + content: + application/json: + schema: + $ref: '#/components/schemas/errdetailsErrorInfo' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UserServiceResendInviteBody' + required: true + /api/v1/memberships/organizations/{organization_id}/users/{id}: + post: + description: Adds an existing user to an organization and assigns them specific roles and permissions. Use this endpoint when you want to grant an existing user access to a particular organization. You can specify roles, metadata, and other membership details during the invitation process. + tags: + - Users + summary: Add existing user to organization + operationId: UserService_CreateMembership + parameters: + - schema: + type: string + description: Unique identifier of the target organization. Must start with 'org_' and be 1-32 characters long. + name: organization_id + in: path + required: true + - schema: + type: string + description: System-generated user ID. Must start with 'usr_' (19-25 characters) + name: id + in: path + required: true + - schema: + type: string + description: External system identifier from connected directories. Must be unique across the system + name: external_id + in: query + - schema: + type: boolean + description: If true, sends an activation email to the user. Defaults to true. + name: send_invitation_email + in: query + responses: + '201': + description: User successfully added to the organization. Returns details of the updated membership details + content: + application/json: + schema: + $ref: '#/components/schemas/usersCreateMembershipResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: "import { ScalekitClient } from \"@scalekit-sdk/node\";\nconst scalekit = new ScalekitClient(\n\tprocess.env.SCALEKIT_ENV_URL,\n\tprocess.env.SCALEKIT_CLIENT_ID,\n\tprocess.env.SCALEKIT_CLIENT_SECRET\n);\nawait scalekit.user.createMembership(\"org_123\", \"usr_123\", {\n\troles: [\"admin\"],\n\tmetadata: {\n\t\tdepartment: \"engineering\",\n\t\tlocation: \"nyc-office\",\n\t},\n});" + - label: Python SDK + lang: python + source: |- + from scalekit.v1.users.users_pb2 import CreateMembership + from scalekit.v1.commons.commons_pb2 import Role + + membership = CreateMembership( + roles=[Role(name="admin")], + metadata={"department": "engineering", "location": "nyc-office"}, + ) + resp = scalekit_client.users.create_membership( + organization_id="org_123", + user_id="usr_123", + membership=membership, + ) + - label: Go SDK + lang: go + source: |- + func main() { + scalekitClient := scalekit.NewScalekitClient( + os.Getenv("SCALEKIT_ENV_URL"), + os.Getenv("SCALEKIT_CLIENT_ID"), + os.Getenv("SCALEKIT_CLIENT_SECRET"), + ) + membership := &usersv1.CreateMembership{ + Roles: []*usersv1.Role{{Name: "admin"}}, + Metadata: map[string]string{ + "department": "engineering", + "location": "nyc-office", + }, + } + resp, + err := scalekitClient.User().CreateMembership( + context.Background(), "org_123", + "usr_123", membership, false) + if err != nil { + panic(err) + } + } + - label: Java SDK + lang: java + source: |- + import com.scalekit.ScalekitClient; + import com.scalekit.api.UserClient; + import com.scalekit.grpc.scalekit.v1.users.*; + ScalekitClient scalekitClient = new ScalekitClient( + System.getenv("SCALEKIT_ENV_URL"), + System.getenv("SCALEKIT_CLIENT_ID"), + System.getenv("SCALEKIT_CLIENT_SECRET") + ); + UserClient users = scalekitClient.users(); + CreateMembershipRequest membershipReq = CreateMemb + ershipRequest.newBuilder() + .setMembership( + CreateMembership.newBuilder() + .addRoles(Role.newBuilder( + ).setName("admin").build()) + .putMetadata("department", "engineering") + .putMetadata("location", "nyc-office") + .build()) + .build(); + CreateMembershipResponse res = users. + createMembership("org_123", "usr_123", + membershipReq); + requestBody: + content: + application/json: + schema: + description: Membership details to create. Required fields must be provided. + required: + - membership + $ref: '#/components/schemas/v1usersCreateMembership' + required: true + delete: + description: Removes a user from an organization by user ID or external ID. If the user has no memberships left and cascade is true, the user is also deleted. This action is irreversible and may also remove related group memberships. + tags: + - Users + summary: Delete organization membership for user + operationId: UserService_DeleteMembership + parameters: + - schema: + type: string + description: Unique organization identifier. Must start with 'org_' and be 1-32 characters long + name: organization_id + in: path + required: true + - schema: + type: string + description: System-generated user ID. Must start with 'usr_' (19-25 characters) + name: id + in: path + required: true + - schema: + type: string + description: External system identifier from connected directories. Must match existing records + name: external_id + in: query + responses: + '200': + description: User successfully marked for deletion. No content returned + content: + application/json: + schema: {} + x-codeSamples: + - label: Python SDK + lang: python + source: |- + response = scalekit_client.users.delete_membership( + organization_id=org_id,user_id=user_id + ) + patch: + description: Updates a user's membership details within an organization by user ID or external ID. You can update roles and membership metadata. + tags: + - Users + summary: Update organization membership for user + operationId: UserService_UpdateMembership + parameters: + - schema: + type: string + description: Unique identifier of the organization containing the membership. Must start with 'org_' and be 1-32 characters long. + name: organization_id + in: path + required: true + - schema: + type: string + description: System-generated user ID. Must start with 'usr_' and be 19-25 characters long. + name: id + in: path + required: true + - schema: + type: string + description: Your application's unique identifier for this user. + name: external_id + in: query + responses: + '200': + description: Membership updated successfully. Returns the updated user object. + content: + application/json: + schema: + $ref: '#/components/schemas/usersUpdateMembershipResponse' + requestBody: + content: + application/json: + schema: + description: Membership fields to update. Only specified fields will be modified. + $ref: '#/components/schemas/v1usersUpdateMembership' + examples: + - role: admin + required: true + /api/v1/organizations: + get: + description: Retrieve a paginated list of organizations within your environment. The response includes a `page_token` that can be used to access subsequent pages of results. + tags: + - Organizations + summary: List organizations + operationId: OrganizationService_ListOrganization + parameters: + - schema: + type: integer + format: int64 + description: Maximum number of organizations to return per page. Must be between 10 and 100 + name: page_size + in: query + - schema: + type: string + description: Pagination token from the previous response. Use to retrieve the next page of organizations + name: page_token + in: query + - schema: + type: string + description: Your application's unique identifier for this organization, used to link Scalekit with your system + name: external_id + in: query + responses: + '200': + description: Successfully retrieved the list of organizations + content: + application/json: + schema: + $ref: '#/components/schemas/organizationsListOrganizationsResponse' + '400': + description: Invalid page token + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: "const organizations = await scalekit.organization.listOrganization({\n\tpageSize: 10,\n});" + - label: Python SDK + lang: python + source: |- + options = ListOrganizationOptions() + options.page_size = 10 + + organizations = scalekit_client.organization.list_organizations( + options=options + ) + - label: Go SDK + lang: go + source: |- + organizations, err := scalekitClient.Organization.ListOrganizations( + ctx, + &scalekit.ListOrganizationOptions{ + PageSize: 10, + } + ) + - label: Java SDK + lang: java + source: ListOrganizationsResponse organizations = scalekitClient.organizations().listOrganizations(10, ""); + post: + description: Creates a new organization in your environment. Use this endpoint to add a new tenant that can be configured with various settings and metadata + tags: + - Organizations + summary: Create an organization + operationId: OrganizationService_CreateOrganization + responses: + '201': + description: Returns the newly created organization with its unique identifier and settings + content: + application/json: + schema: + $ref: '#/components/schemas/organizationsCreateOrganizationResponse' + x-badges: + - name: '' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: "const organization = await scalekit.organization.createOrganization(name, {\n\n\texternalId: \"externalId\",\n\n});" + - label: Python SDK + lang: python + source: |- + options = CreateOrganizationOptions() + options.external_id = "externalId" + organization = scalekit_client.organization.create_organization( + name, + options=options + ) + - label: Go SDK + lang: go + source: |- + organization, err := ScalekitClient.Organization.CreateOrganization( + ctx, + name, + scalekit.CreateOrganizationOptions{ + ExternalID: "externalId", + }, + ) + - label: Java SDK + lang: java + source: |- + CreateOrganization createOrganization = CreateOrganization.newBuilder() + .setDisplayName("Test Org") + .build(); + + Organization createdOrganization = scalekitClient.organizations().create(createOrganization); + requestBody: + content: + application/json: + schema: + description: Required parameters for creating a new organization + $ref: '#/components/schemas/v1organizationsCreateOrganization' + description: Organization details + required: true + /api/v1/organizations/{id}: + get: + description: Retrieves organization details by Scalekit ID, including name, region, metadata, and settings + tags: + - Organizations + summary: Get organization details + operationId: OrganizationService_GetOrganization + parameters: + - schema: + type: string + description: Unique Scalekit-generated identifier for an organization. Use this with the GetOrganization endpoint. Do not pass this parameter when calling GetOrganizationByExternalId — use external_id instead. + name: id + in: path + required: true + responses: + '200': + description: Returns the complete organization object with ID, display name, settings, and metadata + content: + application/json: + schema: + $ref: '#/components/schemas/organizationsGetOrganizationResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + const scalekit = new ScalekitClient( + , + , + + ); + + const organization = await scalekit.organization.getOrganization(organization_id); + - label: Python SDK + lang: python + source: |- + scalekit_client = ScalekitClient( + , + , + + ) + + organization = scalekit_client.organization.get_organization( + organization_id + ) + - label: Go SDK + lang: go + source: |- + scalekitClient := scalekit.NewScalekitClient( + , + , + + ) + + organization, err := scalekitClient.Organization.GetOrganization( + ctx, + organizationId + ) + - label: Java SDK + lang: java + source: |- + ScalekitClient scalekitClient = new ScalekitClient( + "", + "", + "" + ); + + Organization organization = scalekitClient.organizations().getById(organizationId); + delete: + description: Remove an existing organization from the environment using its unique identifier + tags: + - Organizations + summary: Delete an organization + operationId: OrganizationService_DeleteOrganization + parameters: + - schema: + type: string + description: Unique scalekit-generated identifier that uniquely references an organization + name: id + in: path + required: true + responses: + '200': + description: Organization successfully deleted and no longer accessible + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: await scalekit.organization.deleteOrganization(organizationId); + - label: Python SDK + lang: python + source: scalekit_client.organization.delete_organization(organization_id) + - label: Go SDK + lang: go + source: |- + err := scalekitClient.Organization.DeleteOrganization( + ctx, + organizationId + ) + - label: Java SDK + lang: java + source: |- + ScalekitClient scalekitClient = new ScalekitClient( + "", + "", + "" + ); + + scalekitClient.organizations().deleteById(organizationId); + patch: + description: Updates an organization's display name, external ID, or metadata. Requires a valid organization identifier. Region code cannot be modified through this endpoint. + tags: + - Organizations + summary: Update organization details + operationId: OrganizationService_UpdateOrganization + parameters: + - schema: + type: string + description: Unique identifier of the organization to be updated + name: id + in: path + required: true + responses: + '200': + description: Returns the updated organization with all current details reflected in the response. + content: + application/json: + schema: + $ref: '#/components/schemas/organizationsUpdateOrganizationResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + const organization = await scalekit.organization.updateOrganization(organization_id, { + displayName: 'displayName', + externalId: 'externalId', + }); + - label: Python SDK + lang: python + source: |- + organization = scalekit_client.organization.update_organization(organization_id, { + display_name: "display_name", + external_id: "external_id" + }) + - label: Go SDK + lang: go + source: |- + organization, err := scalekitClient.Organization.UpdateOrganization( + ctx, + organizationId, + &scalekit.UpdateOrganization{ + DisplayName: "displayName", + ExternalId: "externalId", + }, + ) + - label: Java SDK + lang: java + source: |- + UpdateOrganization updateOrganization = UpdateOrganization.newBuilder() + .setDisplayName("Updated Organization Name") + .build(); + + Organization updatedOrganizationById = scalekitClient.organizations().updateById(organizationId, updateOrganization); + requestBody: + content: + application/json: + schema: + description: Organization Parameters to be updated + $ref: '#/components/schemas/v1organizationsUpdateOrganization' + required: true + /api/v1/organizations/{id}/portal_links: + put: + description: Creates a single use Admin Portal URL valid for 1 minute. Once the generated admin portal URL is accessed or rendered, a temporary session of 6 hours is created to allow the admin to update SSO/SCIM configuration. + tags: + - Organizations + summary: Generate admin portal link + operationId: OrganizationService_GeneratePortalLink + parameters: + - schema: + type: string + description: Organization ID + name: id + in: path + required: true + - schema: + type: array + items: + enum: + - dir_sync + - sso + type: string + style: form + explode: true + description: |- + Features to enable in the admin portal link. To enable features, append them as URL parameters: + + - Single Sign-On: ?features=sso + - Directory Sync: ?features=dir_sync + - Both features: ?features=sso&features=dir_sync + + Example URL: https://scalekit.com/portal/lnk_123?features=sso + + - dir_sync: Enables directory synchronization configuration in the portal + - sso: Enables Single Sign-On (SSO) configuration in the portal + name: features + in: query + responses: + '200': + description: Admin Portal link generated successfully. Returns the portal URL and expiration timestamp. + content: + application/json: + schema: + $ref: '#/components/schemas/organizationsGeneratePortalLinkResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const link = await scalekit.organization.generatePortalLink(organizationId); + - label: Python SDK + lang: python + source: |- + link = scalekit_client.organization.generate_portal_link( + organization_id + ) + - label: Go SDK + lang: go + source: |- + link, err := scalekitClient.Organization.GeneratePortalLink( + ctx, + organizationId + ) + - label: Java SDK + lang: java + source: |- + Link portalLink = client + .organizations() + .generatePortalLink(organizationId, Arrays.asList(Feature.sso, Feature.dir_sync)); + /api/v1/organizations/{id}/settings: + patch: + description: Updates configuration settings for an organization. Supports modifying SSO configuration, directory synchronization settings, and session parameters. Requires organization ID and the specific settings to update. + tags: + - Organizations + summary: Toggle organization settings + operationId: OrganizationService_UpdateOrganizationSettings + parameters: + - schema: + type: string + description: Unique identifier of the organization to update settings. Must begin with 'org_' prefix + name: id + in: path + required: true + responses: + '200': + description: Returns the complete organization object with updated settings applied. Contains all organization details including ID, display name, and the modified settings. + content: + application/json: + schema: + $ref: '#/components/schemas/organizationsGetOrganizationResponse' + '400': + description: Invalid request - occurs when the settings payload contains invalid values or unsupported configuration + content: + application/json: + schema: {} + '404': + description: Organization not found - the specified organization ID doesn't exist + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + const settings = { + features: [ + { + name: 'sso', + enabled: true, + }, + { + name: 'dir_sync', + enabled: true, + }, + ], + }; + + await scalekit.organization.updateOrganizationSettings('', settings); + - label: Python SDK + lang: python + source: |- + settings = [ + { + "name": "sso", + "enabled": True + }, + { + "name": "dir_sync", + "enabled": True + } + ] + + scalekit_client.organization.update_organization_settings( + organization_id='', settings=settings + ) + - label: Go SDK + lang: go + source: "settings := OrganizationSettings{\n\n\t\tFeatures: []Feature{\n\n\t\t\t{\n\n\t\t\t\tName: \"sso\",\n\n\t\t\t\tEnabled: true,\n\n\t\t\t},\n\n\t\t\t{\n\n\t\t\t\tName: \"dir_sync\",\n\n\t\t\t\tEnabled: true,\n\n\t\t\t},\n\n\t\t},\n\n\t}\n\n\norganization,err := scalekitClient.Organization().UpdateOrganizationSettings(ctx, organizationId, settings)" + - label: Java SDK + lang: java + source: |- + OrganizationSettingsFeature featureSSO = OrganizationSettingsFeature.newBuilder() + .setName("sso") + .setEnabled(true) + .build(); + + OrganizationSettingsFeature featureDirectorySync = OrganizationSettingsFeature.newBuilder() + .setName("dir_sync") + .setEnabled(true) + .build(); + + updatedOrganization = scalekitClient.organizations() + .updateOrganizationSettings(organization.getId(), List.of(featureSSO, + featureDirectorySync)); + requestBody: + content: + application/json: + schema: + description: Settings configuration to apply to the organization. Contains feature toggles for SSO, directory synchronization, and other organization capabilities + $ref: '#/components/schemas/organizationsOrganizationSettings' + examples: + - features: + - enabled: true + name: sso + - enabled: false + name: directory_sync + required: true + /api/v1/organizations/{org_id}/roles: + get: + description: Retrieves all environment roles and organization specific roles. Use this endpoint to view all role definitions, including custom roles and their configurations. You can optionally include permission details for each role to understand their capabilities. This is useful for role management, auditing organization access controls, or understanding the available access levels within the organization. + tags: + - Roles + summary: List organization roles + operationId: RolesService_ListOrganizationRoles + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: org_id + in: path + required: true + - schema: + type: string + description: 'Include additional data in the response. Valid values: ''permissions'' (direct permissions only), ''permissions:all'' (includes inherited permissions)' + name: include + in: query + responses: + '200': + description: Successfully retrieved list of organization roles. Returns all roles with their metadata and optionally their permissions. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesListOrganizationRolesResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const res = await scalekit.role.listOrganizationRoles("org_123"); + - label: Python SDK + lang: python + source: res = scalekit_client.roles.list_organization_roles(org_id="org_123") + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Role().ListOrganizationRoles(ctx, "org_123") + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: ListOrganizationRolesResponse res = scalekitClient.roles().listOrganizationRoles("org_123"); + post: + description: Creates a new role within the specified organization with basic configuration including name, display name, description, and permissions. Use this endpoint to define custom roles that can be assigned to users within the organization. You can create hierarchical roles by extending existing roles and assign specific permissions to control access levels. The role will be scoped to the organization and can be used for organization-specific access control. + tags: + - Roles + summary: Create organization role + operationId: RolesService_CreateOrganizationRole + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: org_id + in: path + required: true + responses: + '201': + description: Organization role created successfully. Returns the complete role object with system-generated ID and timestamps. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesCreateOrganizationRoleResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + await scalekit.role.createOrganizationRole("org_123", { + name: "org_admin", + displayName: "Org Admin", + description: "Organization-scoped role", + extends: "base_role_name", // optional + permissions: ["perm.read", "perm.write"] // optional + }); + - label: Python SDK + lang: python + source: |- + from scalekit.v1.roles.roles_pb2 import CreateOrganizationRole + + role = CreateOrganizationRole( + name="org_admin", + display_name="Org Admin", + description="Organization-scoped role", + extends="base_role_name", # optional + permissions=["perm.read", "perm.write"] # optional + ) + + scalekit_client.roles.create_organization_role( + org_id="org_123", + role=role + ) + - label: Go SDK + lang: go + source: "resp, err := scalekitClient.Role().CreateOrganizationRole(ctx, \"org_123\", &rolesv1.CreateOrganizationRole{\n\n\tName: \"org_admin\",\n\n\tDisplayName: \"Org Admin\",\n\n\tDescription: proto.String(\"Organization-scoped role\"), // optional\n\n\tExtends: proto.String(\"base_role_name\"), // optional\n\n\tPermissions: []string{\"perm.read\", \"perm.write\"}, // optional\n\n})" + - label: Java SDK + lang: java + source: |- + CreateOrganizationRoleResponse res = scalekitClient.roles().createOrganizationRole( + "org_123", + CreateOrganizationRoleRequest.newBuilder() + .setOrgId("org_123") + .setRole( + CreateOrganizationRole.newBuilder() + .setName("org_admin") + .setDisplayName("Org Admin") + .setDescription("Organization-scoped role") + .setExtends("base_role_name") // optional + .addPermissions("perm.read") // optional + .addPermissions("perm.write") // optional + .build() + ) + .build() + ); + requestBody: + content: + application/json: + schema: + description: Organization role details + $ref: '#/components/schemas/v1rolesCreateOrganizationRole' + required: true + /api/v1/organizations/{org_id}/roles/{role_name}: + get: + description: Retrieves complete information for a specific organization role including metadata, inheritance details, and optionally permissions. Use this endpoint to audit role configuration and understand the role's place in the organization's role hierarchy. You can include permission details to see what capabilities the role provides. This operation is useful for role management, user assignment decisions, or understanding organization access controls. + tags: + - Roles + summary: Get organization role details + operationId: RolesService_GetOrganizationRole + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: org_id + in: path + required: true + - schema: + type: string + description: Unique name of the role + name: role_name + in: path + required: true + - schema: + type: string + description: 'Include additional data in the response. Valid values: ''permissions'' (direct permissions only), ''permissions:all'' (includes inherited permissions)' + name: include + in: query + responses: + '200': + description: Successfully retrieved organization role details. Returns the role object including metadata and inheritance details. Permissions are included only when requested via the include parameter. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesGetOrganizationRoleResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const res = await scalekit.role.getOrganizationRole("org_123", "org_admin"); + - label: Python SDK + lang: python + source: |- + res = scalekit_client.roles.get_organization_role( + org_id="org_123", + role_name="org_admin" + ) + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Role().GetOrganizationRole(ctx, "org_123", "org_admin") + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: GetOrganizationRoleResponse res = scalekitClient.roles().getOrganizationRole("org_123", "org_admin"); + put: + description: Modifies an existing organization role's properties including display name, description, permissions, and inheritance settings. Use this endpoint to update role metadata, change permission assignments, or modify role hierarchy within the organization. Only the fields you specify will be updated, leaving other properties unchanged. When updating permissions, the new list replaces all existing permissions for the role. + tags: + - Roles + summary: Update organization role + operationId: RolesService_UpdateOrganizationRole + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: org_id + in: path + required: true + - schema: + type: string + description: Unique name of the role + name: role_name + in: path + required: true + responses: + '200': + description: Organization role updated successfully. Returns the modified role object with updated timestamps. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesUpdateOrganizationRoleResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + await scalekit.role.updateOrganizationRole("org_123", "org_admin", { + displayName: "Org Admin (Updated)", + description: "Updated org role description" + }); + - label: Python SDK + lang: python + source: |- + from scalekit.v1.roles.roles_pb2 import UpdateRole + + scalekit_client.roles.update_organization_role( + org_id="org_123", + role_name="org_admin", + role=UpdateRole( + display_name="Org Admin (Updated)", + description="Updated org role description" + ) + ) + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Role().UpdateOrganizationRole(ctx, "org_123", "org_admin", &rolesv1.UpdateRole{ + DisplayName: "Org Admin (Updated)", + Description: "Updated org role description", + }) + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: |- + UpdateOrganizationRoleResponse res = scalekitClient.roles().updateOrganizationRole( + "org_123", + "org_admin", + UpdateOrganizationRoleRequest.newBuilder() + .setRole( + UpdateRole.newBuilder() + .setDisplayName("Org Admin (Updated)") + .setDescription("Updated org role description") + .build() + ) + .build() + ); + requestBody: + content: + application/json: + schema: + description: Organization role details + $ref: '#/components/schemas/v1rolesUpdateRole' + required: true + delete: + description: Permanently removes a role from the organization and optionally reassigns users who had that role to a different role. Use this endpoint when you need to clean up unused roles or restructure your organization's access control system. If users are assigned to the role being deleted, you can provide a reassign_role_name to move those users to a different role before deletion. This action cannot be undone, so ensure no critical users depend on the role before deletion. + tags: + - Roles + summary: Delete organization role + operationId: RolesService_DeleteOrganizationRole + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: org_id + in: path + required: true + - schema: + type: string + description: Unique name of the role + name: role_name + in: path + required: true + - schema: + type: string + description: Role name to reassign users to when deleting this role + name: reassign_role_name + in: query + responses: + '200': + description: Organization role successfully deleted and users reassigned if specified. No content returned. + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + // Basic delete + await scalekit.role.deleteOrganizationRole("org_123", "org_role_admin"); + + // With reassignment + await scalekit.role.deleteOrganizationRole("org_123", "org_role_admin", "org_role_member"); + - label: Python SDK + lang: python + source: |- + # Basic delete + scalekit_client.roles.delete_organization_role( + org_id="org_123", + role_name="org_role_admin" + ) + + # With reassignment + scalekit_client.roles.delete_organization_role( + org_id="org_123", + role_name="org_role_admin", + reassign_role_name="org_role_member" + ) + - label: Go SDK + lang: go + source: |- + // Basic delete + err := scalekitClient.Role().DeleteOrganizationRole(ctx, "org_123", "org_role_admin") + if err != nil { /* handle err */ } + + // With reassignment + err = scalekitClient.Role().DeleteOrganizationRole(ctx, "org_123", "org_role_admin", "org_role_member") + - label: Java SDK + lang: java + source: |- + // Basic delete + scalekitClient.roles().deleteOrganizationRole("org_123", "org_role_admin"); + + // With reassignment + scalekitClient.roles().deleteOrganizationRole("org_123", "org_role_admin", "org_role_member"); + /api/v1/organizations/{org_id}/roles:set_defaults: + patch: + description: Updates the default member role for the specified organization. Use this endpoint to configure which role is automatically assigned to new users when they join the organization. The system will validate that the specified role exists and update the organization settings accordingly. This configuration affects all new user invitations and memberships within the organization. + tags: + - Roles + summary: Set default organization roles + operationId: RolesService_UpdateDefaultOrganizationRoles + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: org_id + in: path + required: true + responses: + '200': + description: Default organization roles updated successfully. Returns the updated default member role object with complete role information. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesUpdateDefaultOrganizationRolesResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + const res = await scalekit.role.updateDefaultOrganizationRoles("org_123", { + defaultMemberRole: "org_member" + }); + - label: Python SDK + lang: python + source: |- + from scalekit.v1.roles.roles_pb2 import UpdateDefaultOrganizationRolesRequest + + res = scalekit_client.roles.update_default_organization_roles( + org_id="org_123", + default_roles=UpdateDefaultOrganizationRolesRequest( + default_member_role="org_member" + ) + ) + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Role().UpdateDefaultOrganizationRoles(ctx, "org_123", "org_member") + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: |- + UpdateDefaultOrganizationRolesResponse res = scalekitClient.roles().updateDefaultOrganizationRoles( + "org_123", + UpdateDefaultOrganizationRolesRequest.newBuilder() + .setDefaultMemberRole("org_member") + .build() + ); + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RolesServiceUpdateDefaultOrganizationRolesBody' + required: true + /api/v1/organizations/{organization_id}/clients: + get: + description: Retrieves a paginated list of API clients for a specific organization. Returns client details including metadata, scopes, and secret information (without exposing actual secret values). + tags: + - API Auth + summary: List organization API clients + operationId: ClientService_ListOrganizationClients + parameters: + - schema: + type: string + description: Unique identifier of the organization whose clients to list. Must start with 'org_' prefix. + name: organization_id + in: path + required: true + - schema: + type: integer + format: int64 + description: |- + Maximum number of clients to return per page + + Maximum number of API clients to return per page. Must be between 10 and 100 + name: page_size + in: query + - schema: + type: string + description: |- + Pagination token from the previous response + + Pagination token from the previous response. Use to retrieve the next page of organization clients + name: page_token + in: query + responses: + '200': + description: List of organization API clients returned successfully. Each client includes its configuration details and metadata. + content: + application/json: + schema: + $ref: '#/components/schemas/clientsListOrganizationClientsResponse' + x-codeSamples: + - label: Python SDK + lang: python + source: |- + # List clients for a specific organization + org_id = 'SCALEKIT_ORGANIZATION_ID' + + # Retrieve all clients with default pagination + response = scalekit_client.m2m_client.list_organization_clients( + organization_id=org_id, + page_size=30 + ) + + # Access the clients list + clients = response.clients + for client in clients: + print(f"Client ID: {scalekit_client.id}, Name: {scalekit_client.name}") + post: + description: Creates a new API client for an organization. Returns the client details and a plain secret (available only once). + tags: + - API Auth + summary: Create organization API client + operationId: ClientService_CreateOrganizationClient + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + responses: + '201': + description: API client created successfully. Returns the client ID and plain secret (only available at creation time). The client can be configured with scopes, audience values, and custom claims for fine-grained access control. + content: + application/json: + schema: + $ref: '#/components/schemas/clientsCreateOrganizationClientResponse' + x-codeSamples: + - label: Python SDK + lang: python + source: |- + from scalekit.v1.clients.clients_pb2 import OrganizationClient + + m2m_client = OrganizationClient( + name="GitHub Actions Deployment Service", + description="Service account for GitHub Actions to deploy applications + to production", + custom_claims=[ + {"key": "github_repository", "value": "acmecorp/inventory-service"}, + {"key": "environment", "value": "production_us"} + ], + scopes=["deploy:applications", "read:deployments"], + audience=["deployment-api.acmecorp.com"], + expiry=3600 + ) + + response = scalekit_client.m2m_client.create_organization_client( + organization_id="SCALEKIT_ORGANIZATION_ID", + m2m_client=m2m_client + ) + requestBody: + content: + application/json: + schema: + description: Details of the client to be created + $ref: '#/components/schemas/clientsOrganizationClient' + required: true + /api/v1/organizations/{organization_id}/clients/{client_id}: + get: + description: Retrieves details of a specific API client in an organization. + tags: + - API Auth + summary: Get organization API client + operationId: ClientService_GetOrganizationClient + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the API client + name: client_id + in: path + required: true + responses: + '200': + description: Returns the complete API client configuration, including all current settings and a list of active secrets. Note that secret values are not included in the response for security reasons. + content: + application/json: + schema: + $ref: '#/components/schemas/clientsGetOrganizationClientResponse' + x-codeSamples: + - label: Python SDK + lang: python + source: |- + # Get client ID from environment variables + org_id = 'SCALEKIT_ORGANIZATION_ID' + client_id = os.environ['M2M_CLIENT_ID'] + + # Fetch client details for the specified organization + response = scalekit_client.m2m_client.get_organization_client( + organization_id=org_id, + client_id=client_id + ) + delete: + description: Permanently deletes an API client from an organization. This operation cannot be undone and will revoke all access for the client. All associated secrets will also be invalidated. Use this endpoint to remove unused or compromised clients. + tags: + - API Auth + summary: Delete organization API client + operationId: ClientService_DeleteOrganizationClient + parameters: + - schema: + type: string + description: Unique identifier of the organization that owns the client. Must start with 'org_' prefix. + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the API client to permanently delete. Must start with 'm2morg_' prefix. + name: client_id + in: path + required: true + responses: + '200': + description: Organization API client successfully deleted and no longer accessible + content: + application/json: + schema: {} + x-codeSamples: + - label: Python SDK + lang: python + source: |- + # Get client ID from environment variables + org_id = '' + client_id = os.environ['M2M_CLIENT_ID'] + + # Delete the specified client from the organization + response = scalekit_client.m2m_client.delete_organization_client( + organization_id=org_id, + client_id=client_id + ) + patch: + description: Updates an existing organization API client. Only specified fields are modified. + tags: + - API Auth + summary: Update organization API client + operationId: ClientService_UpdateOrganizationClient + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the client + name: client_id + in: path + required: true + responses: + '200': + description: Returns the updated organization API client with all current details reflected in the response, including modified scopes, audience values, and custom claims. + content: + application/json: + schema: + $ref: '#/components/schemas/clientsUpdateOrganizationClientResponse' + x-codeSamples: + - label: Python SDK + lang: python + source: |- + from scalekit.v1.clients.clients_pb2 import OrganizationClient + + org_id = '' + client_id = os.environ['M2M_CLIENT_ID'] + + update_m2m_client = OrganizationClient( + description="Service account for GitHub Actions to deploy applications + to production_eu", + custom_claims=[ + {"key": "github_repository", "value": "acmecorp/inventory"}, + {"key": "environment", "value": "production_eu"} + ] + ) + + response = scalekit_client.m2m_client.update_organization_client( + organization_id=org_id, + client_id=client_id, + m2m_client=update_m2m_client + ) + requestBody: + content: + application/json: + schema: + description: Updated details for the client + $ref: '#/components/schemas/clientsOrganizationClient' + required: true + /api/v1/organizations/{organization_id}/clients/{client_id}/secrets: + post: + description: Creates a new secret for an organization API client. Returns the plain secret (available only once). + tags: + - API Auth + summary: Create organization API client secret + operationId: ClientService_CreateOrganizationClientSecret + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the API client + name: client_id + in: path + required: true + responses: + '201': + description: Client secret created successfully. Returns the new secret ID and the plain secret value (only available at creation time). The secret can be used immediately for authentication. + content: + application/json: + schema: + $ref: '#/components/schemas/clientsCreateOrganizationClientSecretResponse' + x-codeSamples: + - label: Python SDK + lang: python + source: |- + # Get client ID from environment variables + org_id = 'SCALEKIT_ORGANIZATION_ID' + client_id = os.environ['M2M_CLIENT_ID'] + + # Add a new secret to the specified client + response = scalekit_client.m2m_client.add_organization_client_secret( + organization_id=org_id, + client_id=client_id + ) + + # Extract the secret ID from the response + secret_id = response[0].secret.id + /api/v1/organizations/{organization_id}/clients/{client_id}/secrets/{secret_id}: + delete: + description: Permanently deletes a secret from an organization API client. This operation cannot be undone. + tags: + - API Auth + summary: Delete organization API client secret + operationId: ClientService_DeleteOrganizationClientSecret + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the API client + name: client_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the client secret + name: secret_id + in: path + required: true + responses: + '200': + description: Client secret successfully deleted and no longer accessible + content: + application/json: + schema: {} + x-codeSamples: + - label: Python SDK + lang: python + source: |- + # Get client and secret IDs from environment variables + org_id = '' + client_id = os.environ['M2M_CLIENT_ID'] + secret_id = os.environ['M2M_SECRET_ID'] + + # Remove the specified secret from the client + response = scalekit_client.m2m_client.remove_organization_client_secret( + organization_id=org_id, + client_id=client_id, + secret_id=secret_id + ) + /api/v1/organizations/{organization_id}/connections/{id}: + get: + description: Retrieves the complete configuration and status details for a specific connection by its ID within an organization. Returns all connection properties including provider settings, protocols, and current status. + tags: + - Connections + summary: Get connection details + operationId: ConnectionService_GetConnection + parameters: + - schema: + type: string + description: Organization identifier (required). Specifies which organization owns the connection you want to retrieve. + name: organization_id + in: path + required: true + - schema: + type: string + description: Connection identifier (required). Specifies which specific connection to retrieve from the organization. + name: id + in: path + required: true + responses: + '200': + description: Successfully retrieved connection details for the specified organization + content: + application/json: + schema: + $ref: '#/components/schemas/connectionsGetConnectionResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + const connection = await scalekit.connection.getConnection( + organizationId, + connectionId + ); + - label: Python SDK + lang: python + source: |- + connection = scalekit_client.connection.get_connection( + organization_id, + connection_id, + ) + - label: Go SDK + lang: go + source: |- + connection, err := scalekitClient.Connection.GetConnection( + ctx, + organizationId, + connectionId, + ) + - label: Java SDK + lang: java + source: Connection connection = scalekitClient.connections().getConnectionById(connectionId, organizationId); + delete: + description: Deletes an SSO connection from the specified organization by connection ID. Use this endpoint when an identity provider integration is no longer needed for the organization. Returns an empty response after the SSO connection is deleted successfully. + tags: + - Connections + summary: Delete SSO connection + operationId: ConnectionService_DeleteConnection + parameters: + - schema: + type: string + description: Organization ID for the Connection. + name: organization_id + in: path + required: true + - schema: + type: string + description: Connection ID. Unique ID for the connection + name: id + in: path + required: true + responses: + '200': + description: SSO connection deleted successfully + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: await scalekit.connection.deleteConnection(organizationId, connectionId); + - label: Python SDK + lang: python + source: |- + scalekit_client.connection.delete_connection( + organization_id, + connection_id + ) + - label: Go SDK + lang: go + source: |- + err := scalekitClient.Connection.DeleteConnection( + ctx, + organizationId, + connectionId, + ) + - label: Java SDK + lang: java + source: scalekitClient.connections().deleteConnection(connectionId, organizationId); + /api/v1/organizations/{organization_id}/connections/{id}:disable: + patch: + description: Deactivate an existing connection for the specified organization. When disabled, users cannot authenticate using this connection. This endpoint changes the connection state from enabled to disabled without modifying other configuration settings + tags: + - Connections + summary: Disable SSO connection + operationId: ConnectionService_DisableConnection + parameters: + - schema: + type: string + description: Unique identifier of the organization associated with the connection + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier for the connection to be toggled + name: id + in: path + required: true + responses: + '200': + description: Connection disabled successfully + content: + application/json: + schema: + $ref: '#/components/schemas/connectionsToggleConnectionResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: await scalekit.connection.disableConnection(organizationId, connectionId); + - label: Python SDK + lang: python + source: |- + scalekit_client.connection.disable_connection( + organization_id, + connection_id + ) + - label: Go SDK + lang: go + source: |- + err := scalekitClient.Connection.DisableConnection( + ctx, + organizationId, + connectionId, + ) + - label: Java SDK + lang: java + source: ToggleConnectionResponse response = scalekitClient.connections().disableConnection(connectionId, organizationId); + /api/v1/organizations/{organization_id}/connections/{id}:enable: + patch: + description: Activate an existing connection for the specified organization. When enabled, users can authenticate using this connection. This endpoint changes the connection state from disabled to enabled without modifying other configuration settings + tags: + - Connections + summary: Enable SSO connection + operationId: ConnectionService_EnableConnection + parameters: + - schema: + type: string + description: Unique identifier of the organization associated with the connection + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier for the connection to be toggled + name: id + in: path + required: true + responses: + '200': + description: Connection enabled successfully + content: + application/json: + schema: + $ref: '#/components/schemas/connectionsToggleConnectionResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: await scalekit.connection.enableConnection(organizationId, connectionId); + - label: Python SDK + lang: python + source: |- + scalekit_client.connection.enable_connection( + organization_id, + connection_id, + ) + - label: Go SDK + lang: go + source: |- + err := scalekitClient.Connection.EnableConnection( + ctx, + organizationId, + connectionId, + ) + - label: Java SDK + lang: java + source: ToggleConnectionResponse response = scalekitClient.connections().enableConnection(connectionId, organizationId); + /api/v1/organizations/{organization_id}/directories: + get: + tags: + - Directory + summary: List organization directories + operationId: DirectoryService_ListDirectories + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + responses: + '200': + description: Successfully retrieved the list of directories for the organization + content: + application/json: + schema: + $ref: '#/components/schemas/directoriesListDirectoriesResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: await scalekit.directory.listDirectories(''); + - label: Python SDK + lang: python + source: "directories_list = scalekit_client.directory.list_directories(\n\torganization_id=''\n)" + - label: Go SDK + lang: go + source: directories,err := scalekitClient.Directory().ListDirectories(ctx, organizationId) + - label: Java SDK + lang: java + source: ListDirectoriesResponse response = scalekitClient.directories().listDirectories(organizationId); + /api/v1/organizations/{organization_id}/directories/{directory_id}/groups: + get: + description: Retrieves all groups from a specified directory. Use this endpoint to view group structures from your connected identity provider. + tags: + - Directory + summary: List directory groups + operationId: DirectoryService_ListDirectoryGroups + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the directory + name: directory_id + in: path + required: true + - schema: + type: integer + format: int64 + description: Number of groups to return per page. Maximum value is 30. If not specified, defaults to 10 + name: page_size + in: query + - schema: + type: string + description: Token for pagination. Use the value returned in the 'next_page_token' field of the previous response + name: page_token + in: query + - schema: + type: string + format: date-time + description: Filter groups updated after this timestamp. Use ISO 8601 format + name: updated_after + in: query + - schema: + type: boolean + description: If true, includes full group details. If false or not specified, returns basic information only + name: include_detail + in: query + - schema: + type: boolean + description: 'If true, returns group and its details from external provider (default: false)' + name: include_external_groups + in: query + responses: + '200': + description: Successfully retrieved the list of groups from the specified directory + content: + application/json: + schema: + $ref: '#/components/schemas/directoriesListDirectoryGroupsResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + const { groups } = await scalekit.directory.listDirectoryGroups( + '', + '' + ); + - label: Python SDK + lang: python + source: |- + directory_groups = scalekit_client.directory.list_directory_groups( + directory_id='', organization_id='' + ) + - label: Go SDK + lang: go + source: "options := &ListDirectoryGroupsOptions{\n\n\t\tPageSize: 10,\n\n\t\tPageToken:\"\",\n\n\t}\n\n\ndirectoryGroups, err := scalekitClient.Directory().ListDirectoryGroups(ctx, organizationId, directoryId, options)" + - label: Java SDK + lang: java + source: |- + var options = ListDirectoryResourceOptions.builder() + .pageSize(10) + .pageToken("") + .includeDetail(true) + .build(); + + ListDirectoryGroupsResponse groupsResponse = scalekitClient + .directories() + .listDirectoryGroups(directory.getId(), organizationId, options); + /api/v1/organizations/{organization_id}/directories/{directory_id}/users: + get: + description: Retrieves a list of all users within a specified directory for an organization. This endpoint allows you to view user accounts associated with your connected Directory Providers. + tags: + - Directory + summary: List directory users + operationId: DirectoryService_ListDirectoryUsers + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the directory within the organization + name: directory_id + in: path + required: true + - schema: + type: integer + format: int64 + description: Number of users to return per page. Maximum value is 30. If not specified, defaults to 10 + name: page_size + in: query + - schema: + type: string + description: Token for pagination. Use the value returned in the 'next_page_token' field of the previous response to retrieve the next page of results + name: page_token + in: query + - schema: + type: boolean + description: If set to true, the response will include the full user payload with all available details. If false or not specified, only essential user information will be returned + name: include_detail + in: query + - schema: + type: string + description: Filter users by their membership in a specific directory group + name: directory_group_id + in: query + - schema: + type: string + format: date-time + description: Filter users that were updated after the specified timestamp. Use ISO 8601 format + name: updated_after + in: query + responses: + '200': + description: Successfully retrieved the list of users from the specified directory + content: + application/json: + schema: + $ref: '#/components/schemas/directoriesListDirectoryUsersResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + const { users } = await scalekit.directory.listDirectoryUsers( + '', + '' + ); + - label: Python SDK + lang: python + source: |- + directory_users = scalekit_client.directory.list_directory_users( + directory_id='', organization_id='' + ) + - label: Go SDK + lang: go + source: "options := &ListDirectoryUsersOptions{\n\n\t\tPageSize: 10,\n\n\t\tPageToken: \"\",\n\n\t}\n\ndirectoryUsers,err := scalekitClient.Directory().ListDirectoryUsers(ctx, organizationId, directoryId, options)" + - label: Java SDK + lang: java + source: |- + var options = ListDirectoryResourceOptions.builder() + .pageSize(10) + .pageToken("") + .includeDetail(true) + .build(); + + ListDirectoryUsersResponse usersResponse = scalekitClient + .directories() + .listDirectoryUsers(directory.getId(), organizationId, options); + /api/v1/organizations/{organization_id}/directories/{id}: + get: + description: Retrieves detailed information about a specific directory within an organization + tags: + - Directory + summary: Get directory details + operationId: DirectoryService_GetDirectory + parameters: + - schema: + type: string + description: Unique identifier of the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier of the directory + name: id + in: path + required: true + responses: + '200': + description: Successfully retrieved directory details + content: + application/json: + schema: + $ref: '#/components/schemas/directoriesGetDirectoryResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + const { directory } = await scalekit.directory.getDirectory( + organizationId, + directoryId + ); + - label: Python SDK + lang: python + source: |- + directory = scalekit_client.directory.get_directory( + directory_id='', organization_id='' + ) + print(f'Directory details: {directory}') + - label: Go SDK + lang: go + source: directory, err := scalekitClient.Directory().GetDirectory(ctx, organizationId, directoryId) + - label: Java SDK + lang: java + source: Directory directory = scalekitClient.directories().getDirectory(directoryId, organizationId); + /api/v1/organizations/{organization_id}/directories/{id}:disable: + patch: + description: Stops synchronization of users and groups from a specified directory within an organization. This operation prevents further updates from the connected Directory provider + tags: + - Directory + summary: Disable a directory + operationId: DirectoryService_DisableDirectory + parameters: + - schema: + type: string + description: A unique identifier for the organization. The value must begin with 'org_' and be between 1 and 32 characters long + name: organization_id + in: path + required: true + - schema: + type: string + description: A unique identifier for a directory within the organization. The value must begin with 'dir_' and be between 1 and 32 characters long + name: id + in: path + required: true + responses: + '200': + description: Successfully disabled the directory + content: + application/json: + schema: + $ref: '#/components/schemas/directoriesToggleDirectoryResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + await scalekit.directory.disableDirectory( + '', + '' + ); + - label: Python SDK + lang: python + source: |- + directory_response = scalekit_client.directory.disable_directory( + directory_id='', organization_id='' + ) + - label: Go SDK + lang: go + source: disable,err := scalekitClient.Directory().DisableDirectory(ctx, organizationId, directoryId) + - label: Java SDK + lang: java + source: |- + ToggleDirectoryResponse disableResponse = scalekitClient + .directories() + .disableDirectory(directoryId, organizationId); + /api/v1/organizations/{organization_id}/directories/{id}:enable: + patch: + description: Activates a directory within an organization, allowing it to synchronize users and groups with the connected Directory provider + tags: + - Directory + summary: Enable a directory + operationId: DirectoryService_EnableDirectory + parameters: + - schema: + type: string + description: A unique identifier for the organization. The value must begin with 'org_' and be between 1 and 32 characters long + name: organization_id + in: path + required: true + - schema: + type: string + description: A unique identifier for a directory within the organization. The value must begin with 'dir_' and be between 1 and 32 characters long + name: id + in: path + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/directoriesToggleDirectoryResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: await scalekit.directory.enableDirectory('', ''); + - label: Python SDK + lang: python + source: |- + directory_response = scalekit_client.directory.enable_directory( + directory_id='', organization_id='' + ) + - label: Go SDK + lang: go + source: enable,err := scalekitClient.Directory().EnableDirectory(ctx, organizationId, directoryId) + - label: Java SDK + lang: java + source: |- + ToggleDirectoryResponse enableResponse = client + .directories() + .enableDirectory(directoryId, organizationId); + /api/v1/organizations/{organization_id}/domains: + get: + description: |+ + Retrieves a paginated list of all domains configured for the specified organization. + + Domain types: + - ALLOWED_EMAIL_DOMAIN: Trusted domains used to suggest the organization in the organization switcher during sign-in/sign-up (auth-method agnostic). + - ORGANIZATION_DOMAIN: SSO discovery domains used to route users to the correct SSO provider and enforce SSO. + + tags: + - Domains + summary: List Domains + operationId: DomainService_ListDomains + parameters: + - schema: + type: string + description: Scalekit-generated unique identifier for the organization. Use either this or external_id to identify the organization. + name: organization_id + in: path + required: true + - schema: + type: string + description: Optional comma-separated list of additional fields to include in the response (e.g., 'verification_details'). + name: include + in: query + - schema: + type: integer + format: int32 + description: Maximum number of domains to return per page. Default is 30, maximum is 100. + name: page_size + in: query + - schema: + type: integer + format: int32 + description: Page number to retrieve (0-based). Use 0 for the first page. + name: page_number + in: query + - schema: + type: string + enum: + - ALLOWED_EMAIL_DOMAIN + - ORGANIZATION_DOMAIN + description: | + The domain type. + - ALLOWED_EMAIL_DOMAIN: trusted domain used to suggest the organization in the organization switcher during sign-in/sign-up. + - ORGANIZATION_DOMAIN: SSO discovery domain used to route users to the correct SSO provider and enforce SSO. + name: domain_type + in: query + responses: + '200': + description: Successfully retrieved the list of domains. + content: + application/json: + schema: + $ref: '#/components/schemas/domainsListDomainResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: "// List all domains in an organization\nconst response = await scalekit.domain.listDomains(organizationId, {\n\tdomainType: \"ORGANIZATION_DOMAIN\"\n});\n\n// Domain object contains:\n// - id: Domain identifier\n// - domain: Domain name\n// - organizationId: Owning organization\n// - domainType: Configuration type" + - label: Python SDK + lang: python + source: |- + # List all domains in an organization + response = scalekit_client.domain.list_domains( + organization_id="org_123", + domain_type="ORGANIZATION_DOMAIN" + ) + # - organization_id: Owning organization + # - domain_type: domain type + - label: Go SDK + lang: go + source: |- + domains, err := scalekitClient.Domain().ListDomains(ctx, "org_id", &scalekit.ListDomainOptions{ + DomainType: "ORGANIZATION_DOMAIN", + }) + - label: Java SDK + lang: java + source: List domains = scalekitClient.domains().listDomainsByOrganizationId("org_id", "ORGANIZATION_DOMAIN"); + post: + description: |+ + Creates and associates a domain with an organization. + + Use one of the following domain types: + - ALLOWED_EMAIL_DOMAIN: Adds a trusted email domain for organization suggestions in the organization switcher during sign-in/sign-up (auth-method agnostic). + - ORGANIZATION_DOMAIN: Enables SSO domain discovery. If a user signs in with a matching email domain, Scalekit redirects them to the organization’s SSO provider and enforces SSO. + + The domain must be a valid business domain that you control. Public/disposable domains (e.g., gmail.com) are blocked for security. + + tags: + - Domains + summary: Create Domain + operationId: DomainService_CreateDomain + parameters: + - schema: + type: string + description: Scalekit-generated unique identifier for the organization. Use either this or external_id to identify the organization. + name: organization_id + in: path + required: true + responses: + '200': + description: Successfully created the domain. + content: + application/json: + schema: + $ref: '#/components/schemas/domainsCreateDomainResponse' + '400': + description: Invalid request — common causes invalid domain format, public or disposable domain, or domain already exists. + content: + application/json: + schema: + $ref: '#/components/schemas/errdetailsErrorInfo' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: "// Add a new domain to an organization\nconst response = await scalekit.createDomain(\"org-123\", \"example.com\", {\n\n\t// Domain type: controls user authentication and email validation\n\n\tdomainType: \"ORGANIZATION_DOMAIN\",\n\n});" + - label: Python SDK + lang: python + source: "# Add a new domain to an organization\nresponse = scalekit_client.domain.create_domain(organization_id=\"org-123\",\n\n\t\t\tdomain_name=\"example.com\",\n \t\t\tdomain_type=\"ORGANIZATION_DOMAIN\")" + - label: Go SDK + lang: go + source: "domain, err := scalekitClient.Domain().CreateDomain(ctx, \"org_id\", \"example.com\", &scalekit.CreateDomainOptions{\n\n\t\tDomainType: \"ORGANIZATION_DOMAIN\",\n\n\t})" + - label: Java SDK + lang: java + source: "CreateDomainRequest request = CreateDomainRequest.newBuilder()\n\t.setOrganizationId(organization.getId())\n\t.setDomain(CreateDomain.newBuilder()\n\t\t.setDomain(\"example.com\")\n\t\t.setDomainType(\"ORGANIZATION_DOMAIN\")\n\t\t.build())\n\t.build();\n\t\nDomain domain = scalekitClient.domains().createDomain(request);" + requestBody: + content: + application/json: + schema: + description: Domain configuration including the domain name and type. + $ref: '#/components/schemas/v1domainsCreateDomain' + required: true + /api/v1/organizations/{organization_id}/domains/{id}: + get: + description: |+ + Retrieves complete details for a domain including domain type, timestamps, and configuration information. + + tags: + - Domains + summary: Get Domain + operationId: DomainService_GetDomain + parameters: + - schema: + type: string + description: Scalekit-generated unique identifier for the organization. Use either this or external_id to identify the organization. + name: organization_id + in: path + required: true + - schema: + type: string + description: Scalekit-generated unique identifier of the domain to retrieve. + name: id + in: path + required: true + responses: + '200': + description: Successfully retrieved the domain details. + content: + application/json: + schema: + $ref: '#/components/schemas/domainsGetDomainResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + // Fetch details of a specific domain + const response = await scalekit.domain.getDomain(organizationId, domainId); + + // Domain object properties: + // - id: Domain identifier + // - domain: Domain name + // - organizationId: Owning organization + // - domainType: Domain configuration type + - label: Python SDK + lang: python + source: |- + # Fetch details of a specific domain + response = scalekit_client.domain.get_domain(organization_id="org_123", domain_id="dom_123") + - label: Go SDK + lang: go + source: domain, err := scalekitClient.Domain().GetDomain(ctx, "dom_123", "org_123") + - label: Java SDK + lang: java + source: Domain domain = scalekitClient.domains().getDomainById("org_123", "dom_123"); + delete: + description: |+ + Permanently removes a domain record from an organization. + + - Deleting an ORGANIZATION_DOMAIN disables SSO routing/enforcement for that domain. + - Deleting an ALLOWED_EMAIL_DOMAIN stops organization suggestions for users with that email domain. + + tags: + - Domains + summary: Delete Domain + operationId: DomainService_DeleteDomain + parameters: + - schema: + type: string + description: Scalekit-generated unique identifier for the organization. Use either this or external_id to identify the organization. + name: organization_id + in: path + required: true + - schema: + type: string + description: Scalekit-generated unique identifier of the domain to be permanently deleted. + name: id + in: path + required: true + responses: + '200': + description: Domain successfully deleted. + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + // Remove a domain from an organization + // Caution: Deletion is permanent and may affect user access + const response = await scalekit.domain.deleteDomain(organizationId, domainId); + - label: Python SDK + lang: python + source: |- + # Remove a domain from an organization + # Caution: Deletion is permanent and may affect user access + response = scalekit_client.domain.delete_domain( + organization_id="org_123", + domain_id="dom_123" + ) + - label: Go SDK + lang: go + source: err = scalekitClient.Domain().DeleteDomain(ctx, "dom_123", "org_123") + - label: Java SDK + lang: java + source: scalekitClient.domains().deleteDomain(organization.getId(), domain.getId()); + /api/v1/organizations/{organization_id}/session-policy: + get: + description: Retrieves the session policy for an organization. Returns session_policy='APPLICATION' if the organization inherits the application-level defaults, or session_policy='CUSTOM' with the configured values if a custom policy is active. + tags: + - Organizations + summary: Get organization session policy + operationId: OrganizationService_GetOrganizationSessionPolicy + parameters: + - schema: + type: string + description: The unique identifier of the organization whose session policy is being requested. + name: organization_id + in: path + required: true + responses: + '200': + description: Session policy retrieved successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/organizationsGetOrganizationSessionPolicyResponse' + '404': + description: Organization not found. + content: + application/json: + schema: {} + patch: + description: Sets a custom session policy for an organization or reverts to application-level settings. Send session_policy='APPLICATION' to revert to application defaults. Send session_policy='CUSTOM' with timeout values to activate a custom policy. + tags: + - Organizations + summary: Update organization session policy + operationId: OrganizationService_UpdateOrganizationSessionPolicy + parameters: + - schema: + type: string + description: The unique identifier of the organization whose session policy is being updated. + name: organization_id + in: path + required: true + responses: + '200': + description: Session policy updated successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/organizationsUpdateOrganizationSessionPolicyResponse' + '404': + description: Organization not found. + content: + application/json: + schema: {} + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationServiceUpdateOrganizationSessionPolicyBody' + required: true + /api/v1/organizations/{organization_id}/settings/usermanagement: + patch: + description: Upsert user management settings for an organization + tags: + - Organizations + summary: Upsert organization user setting + operationId: OrganizationService_UpsertUserManagementSettings + parameters: + - schema: + type: string + description: ID of the organization. + name: organization_id + in: path + required: true + responses: + '200': + description: Returns the updated organization setting. + content: + application/json: + schema: + $ref: '#/components/schemas/organizationsUpsertUserManagementSettingsResponse' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationServiceUpsertUserManagementSettingsBody' + required: true + /api/v1/organizations/{organization_id}/users: + get: + description: Retrieves a paginated list of all users who are members of the specified organization. Use this endpoint to view all users with access to a particular organization, including their roles, metadata, and membership details. Supports pagination for large user lists. + tags: + - Users + summary: List organization users + operationId: UserService_ListOrganizationUsers + parameters: + - schema: + type: string + description: Unique identifier of the organization for which to list users. Must start with 'org_' and be 1-32 characters long. + name: organization_id + in: path + required: true + - schema: + type: integer + format: int64 + description: 'Maximum number of users to return in a single response. Valid range: 1-100. Server may return fewer users than specified.' + name: page_size + in: query + - schema: + type: string + description: Pagination token from a previous ListUserResponse. Used to retrieve the next page of results. Leave empty for the first request. + name: page_token + in: query + responses: + '200': + description: Successfully retrieved the list of users in the organization + content: + application/json: + schema: + $ref: '#/components/schemas/usersListOrganizationUsersResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: "const response = await scalekit.user.\n listOrganizationUsers(\"org_123\", {\n\tpageSize: 50,\n});\nconsole.log(response.users);" + - label: Python SDK + lang: python + source: resp, _ = scalekit_client.users.list_users(organization_id="org_123", page_size=50) + - label: Go SDK + lang: go + source: |- + list, + err := scalekitClient.User().ListOrganizationUsers(ctx, "org_123", &scalekit.ListUsersOptions{PageSize: + 50}) if err != nil { /* handle error */ } + fmt.Println(list.Users) + - label: Java SDK + lang: java + source: |- + ListOrganizationUsersRequest listReq = ListOrganiz + ationUsersRequest.newBuilder() + .setPageSize(50) + .build(); + ListOrganizationUsersResponse list = users. + listOrganizationUsers("org_123", listReq); + post: + description: Creates a new user account and immediately adds them to the specified organization. Use this endpoint when you want to create a user and grant them access to an organization in a single operation. You can provide user profile information, assign roles, and configure membership metadata. The user receives an activation email unless this feature is disabled in the organization settings. + tags: + - Users + summary: Create new user in organization + operationId: UserService_CreateUserAndMembership + parameters: + - schema: + type: string + name: organization_id + in: path + required: true + - schema: + type: boolean + description: If true, sends an activation email to the user. Defaults to true. + name: send_invitation_email + in: query + responses: + '201': + description: User created successfully. Returns the created user object, including system-generated identifiers and timestamps + content: + application/json: + schema: + $ref: '#/components/schemas/usersCreateUserAndMembershipResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: "const {\n user } = await scalekit.user.\n createUserAndMembership(\"org_123\", {\n\temail: \"user@example.com\",\n\texternalId: \"ext_12345a67b89c\",\n\tmetadata: { department: \"engineering\", \n\t location: \"nyc-office\" },\n\tuserProfile: {\n\t\tfirstName: \"John\",\n\t\tlastName: \"Doe\",\n\t},\n});" + - label: Python SDK + lang: python + source: |- + # Create user with membership + user = CreateUser( + email="john.doe@example.com", + external_id="ext_john_123", # Optional + user_profile={ + "first_name": "John", + "last_name": "Doe", + "name": "John Doe", + "locale": "en-US", + "phone_number": "+14155552671" + }, + membership={ + "roles": [{"name": "member"}] + } + ) + + # Create user and membership in organization + response = scalekit_client.users.create_user_and_membership( + organization_id="your_org_id", + user=user, + send_invitation_email=True # Set to False if you don't want to send + email ) + + user_id = response[0].user.id + - label: Go SDK + lang: go + source: |- + newUser := &usersv1.CreateUser{ + Email: "user@example.com", + ExternalId: "ext_12345a67b89c", + Metadata: map[string]string{ + "department": "engineering", + "location": "nyc-office", + }, + UserProfile: &usersv1.CreateUserProfile{ + FirstName: "John", + LastName: "Doe", + }, + } + cuResp, + err := scalekitClient.User().CreateUserAndMembership(ctx, "org_123", + newUser, false) if err != nil { /* handle error */ } + - label: Java SDK + lang: java + source: |- + CreateUser createUser = CreateUser.newBuilder() + .setEmail("user@example.com") + .setExternalId("ext_12345a67b89c") + .putMetadata("department", "engineering") + .putMetadata("location", "nyc-office") + .setUserProfile( + CreateUserProfile.newBuilder() + .setFirstName("John") + .setLastName("Doe") + .build()) + .build(); + CreateUserAndMembershipRequest cuReq = CreateUserA + ndMembershipRequest.newBuilder() + .setUser(createUser) + .build(); + CreateUserAndMembershipResponse cuResp = users. + createUserAndMembership("org_123", cuReq); + System.out.println(cuResp.getUser().getId()); + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/usersCreateUser' + required: true + /api/v1/organizations/{organization_id}/users/{user_id}/permissions: + get: + description: Retrieves all permissions a user has access to within a specific organization. This includes permissions from direct role assignments and inherited permissions from role hierarchy. + tags: + - Users + summary: List user permissions + operationId: UserService_ListUserPermissions + parameters: + - schema: + type: string + description: Unique identifier for the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier for the user + name: user_id + in: path + required: true + responses: + '200': + description: Successfully retrieved the list of permissions for the user + content: + application/json: + schema: + $ref: '#/components/schemas/usersListUserPermissionsResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const { permissions } = await scalekit.user.listUserPermissions("org_123", "usr_123"); + - label: Python SDK + lang: python + source: |- + resp = scalekit_client.users.list_user_permissions( + organization_id="org_123", + user_id="usr_123", + ) + permissions = resp.permissions + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.User().ListUserPermissions(ctx, "org_123", "usr_123") + if err != nil { + // handle error + } + permissions := resp.Permissions + - label: Java SDK + lang: java + source: |- + ListUserPermissionsResponse resp = scalekitClient.users().listUserPermissions("org_123", "usr_123"); + List permissions = resp.getPermissionsList(); + /api/v1/organizations/{organization_id}/users/{user_id}/roles: + get: + description: Retrieves all roles assigned to a user within a specific organization. This includes both direct role assignments and inherited roles from role hierarchy. + tags: + - Users + summary: List user roles + operationId: UserService_ListUserRoles + parameters: + - schema: + type: string + description: Unique identifier for the organization + name: organization_id + in: path + required: true + - schema: + type: string + description: Unique identifier for the user + name: user_id + in: path + required: true + responses: + '200': + description: Successfully retrieved the list of roles assigned to the user + content: + application/json: + schema: + $ref: '#/components/schemas/usersListUserRolesResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const { roles } = await scalekit.user.listUserRoles("org_123", "usr_123"); + - label: Python SDK + lang: python + source: |- + resp = scalekit_client.users.list_user_roles( + organization_id="org_123", + user_id="usr_123", + ) + roles = resp.roles + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.User().ListUserRoles(ctx, "org_123", "usr_123") + if err != nil { + // handle error + } + roles := resp.Roles + - label: Java SDK + lang: java + source: |- + ListUserRolesResponse resp = scalekitClient.users().listUserRoles("org_123", "usr_123"); + List roles = resp.getRolesList(); + /api/v1/organizations/{organization_id}/users:search: + get: + description: Searches for users within a specific organization by email address, user ID, or external ID. The query must be at least 3 characters and is case-insensitive. Scopes results strictly to the given organization. Returns a paginated list of matching users with up to 30 results per page. Use the next_page_token from the response to retrieve subsequent pages. + tags: + - Users + summary: Search organization users + operationId: UserService_SearchOrganizationUsers + parameters: + - schema: + type: string + description: Unique identifier of the organization to search within. Must start with 'org_' and be 1-32 characters long. + name: organization_id + in: path + required: true + - schema: + type: string + minLength: 3 + maxLength: 100 + description: Search term to match against user email, IDs, or external IDs. Must be at least 3 characters. Case insensitive. + name: query + in: query + required: true + - schema: + type: integer + format: int64 + minimum: 1 + maximum: 30 + description: Maximum number of users to return per page. Value must be between 1 and 30. + name: page_size + in: query + - schema: + type: string + description: Token from a previous response for pagination. Provide this to retrieve the next page of results. + name: page_token + in: query + responses: + '200': + description: Matching users within the organization returned; includes pagination cursors for navigating large result sets. + content: + application/json: + schema: + $ref: '#/components/schemas/usersSearchOrganizationUsersResponse' + '400': + description: Bad Request - query must be at least 3 characters and no more than 100 characters, and organization_id must be a valid org_ prefixed identifier. + content: + application/json: + schema: {} + '404': + description: Not Found - organization not found. + content: + application/json: + schema: {} + /api/v1/organizations:external/{external_id}: + get: + description: Retrieves organization details by external ID, including name, region, metadata, and settings. Only provide external_id in the path. If the id query parameter is also supplied, it silently takes precedence over external_id due to protobuf oneof semantics, which causes the request to fail with a 400 Bad Request ('ExternalId is required'). + tags: + - Organizations + summary: Get organization details by external Id + operationId: OrganizationService_GetOrganizationByExternalId + parameters: + - schema: + type: string + description: Unique identifier that links an organization to your app's tenant. Use this with the GetOrganizationByExternalId endpoint. Only one of id or external_id should be provided per request. + name: external_id + in: path + required: true + - schema: + type: string + description: Unique Scalekit-generated identifier for an organization. Use this with the GetOrganization endpoint. Do not pass this parameter when calling GetOrganizationByExternalId — use external_id instead. + name: id + in: query + responses: + '200': + description: Returns the complete organization object with ID, display name, settings, external ID and metadata + content: + application/json: + schema: + $ref: '#/components/schemas/organizationsGetOrganizationResponse' + '400': + description: Invalid request - external ID is empty or the caller's organization claim does not match + content: + application/json: + schema: {} + '404': + description: Organization not found - no organization exists with the specified external ID + content: + application/json: + schema: {} + /api/v1/passwordless/email/resend: + post: + description: Resend a verification email if the user didn't receive it or if the previous code/link has expired + tags: + - Magic link & OTP + summary: Resend passwordless email + operationId: PasswordlessService_ResendPasswordlessEmail + responses: + '200': + description: Successfully resent the passwordless authentication email. Returns updated authentication request details with new expiration time. + content: + application/json: + schema: + $ref: '#/components/schemas/passwordlessSendPasswordlessResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: "const { authRequestId } = sendResponse;\nconst resendResponse = await scalekit.passwordless.resendPasswordlessEmail(\n\n\tauthRequestId\n\n);" + - label: Python SDK + lang: python + source: |- + resend_response = scalekit_client.passwordless.resend_passwordless_email( + auth_request_id=auth_request_id, + ) + + # New auth request ID from resend + new_auth_request_id = resend_response[0].auth_request_id + - label: Go SDK + lang: go + source: |- + resendResponse, err := scalekitClient.Passwordless().ResendPasswordlessEmail( + ctx, + authRequestId, + ) + + if err != nil { + // Handle error + return + } + - label: Java SDK + lang: java + source: SendPasswordlessResponse resendResponse = passwordlessClient.resendPasswordlessEmail(authRequestId); + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/passwordlessResendPasswordlessRequest' + required: true + /api/v1/passwordless/email/send: + post: + description: Send a verification email containing either a verification code (OTP), magic link, or both to a user's email address + tags: + - Magic link & OTP + summary: Send passwordless email + operationId: PasswordlessService_SendPasswordlessEmail + responses: + '200': + description: Successfully sent passwordless authentication email. Returns the authentication request details including expiration time and auth request ID + content: + application/json: + schema: + $ref: '#/components/schemas/passwordlessSendPasswordlessResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: "const response = await scalekit.passwordless.sendPasswordlessEmail(\n\t\"john.doe@example.com\",\n\t{\n\t\ttemplate: \"SIGNIN\",\n\t\texpiresIn: 100,\n\t\tmagiclinkAuthUri: \"https://www.google.com\",\n\t\ttemplateVariables: {\n\t\t\temployeeID: \"EMP523\",\n\t\t\tteamName: \"Alpha Team\",\n\t\t\tsupportEmail: \"support@yourcompany.com\",\n\t\t},\n\t}\n);" + - label: Python SDK + lang: python + source: |- + response = scalekit_client.passwordless.send_passwordless_email( + email="john.doe@example.com", + template="SIGNIN", # or "SIGNUP", "UNSPECIFIED" + expires_in=100, + magiclink_auth_uri="https://www.google.com", + template_variables={ + "employeeID": "EMP523", + "teamName": "Alpha Team", + "supportEmail": "support@yourcompany.com", + }, + ) + + # Extract auth request ID from response + auth_request_id = response[0].auth_request_id + - label: Go SDK + lang: go + source: |- + templateType := scalekit.TemplateTypeSignin + response, err := scalekitClient.Passwordless().SendPasswordlessEmail( + ctx, + "john.doe@example.com", + &scalekit.SendPasswordlessOptions{ + Template: &templateType, + ExpiresIn: 100, + MagiclinkAuthUri: "https://www.google.com", + TemplateVariables: map[string]string{ + "employeeID": "EMP523", + "teamName": "Alpha Team", + "supportEmail": "support@yourcompany.com", + }, + }, + ) + + if err != nil { + // Handle error + return + } + + authRequestId := response.AuthRequestId + - label: Java SDK + lang: java + source: |- + TemplateType templateType = TemplateType.SIGNIN; + Map templateVariables = new HashMap<>(); + templateVariables.put("employeeID", "EMP523"); + templateVariables.put("teamName", "Alpha Team"); + templateVariables.put("supportEmail", "support@yourcompany.com"); + + SendPasswordlessOptions options = new SendPasswordlessOptions(); + options.setTemplate(templateType); + options.setExpiresIn(100); + options.setMagiclinkAuthUri("https://www.example.com"); + options.setTemplateVariables(templateVariables); + + SendPasswordlessResponse response = passwordlessClient.sendPasswordlessEmail( + "john.doe@example.com", + options + ); + + String authRequestId = response.getAuthRequestId(); + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/passwordlessSendPasswordlessRequest' + required: true + /api/v1/passwordless/email/verify: + post: + description: Verify a user's identity using either a verification code or magic link token + tags: + - Magic link & OTP + summary: Verify passwordless email + operationId: PasswordlessService_VerifyPasswordlessEmail + responses: + '200': + description: Successfully verified the passwordless authentication. Returns user email + content: + application/json: + schema: + $ref: '#/components/schemas/passwordlessVerifyPasswordLessResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: "const { authRequestId } = sendResponse;\nconst verifyResponse = await scalekit.passwordless.verifyPasswordlessEmail(\n\n\t// Verification Code (OTP)\n\n\t{ code: \"123456\" },\n\n\t// Magic Link Token\n\n\t{ linkToken: link_token },\n\n\tauthRequestId\n\n);" + - label: Python SDK + lang: python + source: |- + # Verify with OTP code + verify_response = scalekit_client.passwordless.verify_passwordless_email( + code="123456", # OTP code received via email + auth_request_id=auth_request_id, + ) + + # Verify with magic link token + verify_response = scalekit_client.passwordless.verify_passwordless_email( + link_token=link_token, # Magic link token from URL + ) + + # User verified successfully + user_email = verify_response[0].email + - label: Go SDK + lang: go + source: |- + // Verify with OTP code + verifyResponse, err := scalekitClient.Passwordless().VerifyPasswordlessEmail( + ctx, + &scalekit.VerifyPasswordlessOptions{ + Code: "123456", // OTP code + AuthRequestId: authRequestId, + }, + ) + + if err != nil { + // Handle error + return + } + + // Verify with magic link token + verifyResponse, err := scalekitClient.Passwordless().VerifyPasswordlessEmail( + ctx, + &scalekit.VerifyPasswordlessOptions{ + LinkToken: linkToken, // Magic link token + }, + ) + + if err != nil { + // Handle error + return + } + + // User verified successfully + userEmail := verifyResponse.Email + - label: Java SDK + lang: java + source: |- + // Verify with OTP code + VerifyPasswordlessOptions verifyOptions = new VerifyPasswordlessOptions(); + verifyOptions.setCode("123456"); // OTP code + verifyOptions.setAuthRequestId(authRequestId); + + VerifyPasswordLessResponse verifyResponse = passwordlessClient.verifyPasswordlessEmail(verifyOptions); + + // User verified successfully + String userEmail = verifyResponse.getEmail(); + + // Verify with magic link token + VerifyPasswordlessOptions verifyOptions = new VerifyPasswordlessOptions(); + verifyOptions.setLinkToken(linkToken); // Magic link token + + VerifyPasswordLessResponse verifyResponse = passwordlessClient.verifyPasswordlessEmail(verifyOptions); + + // User verified successfully + String userEmail = verifyResponse.getEmail(); + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/passwordlessVerifyPasswordLessRequest' + required: true + /api/v1/permissions: + get: + description: Retrieves a comprehensive, paginated list of all permissions available within the environment. Use this endpoint to view all permission definitions for auditing, role management, or understanding the complete set of available access controls. The response includes pagination tokens to navigate through large sets of permissions efficiently. Each permission object contains the permission name, description, creation time, and last update time. This operation is useful for building permission selection interfaces, auditing permission usage, or understanding the scope of available access controls in your RBAC system. + tags: + - Permissions + summary: List all permissions + operationId: RolesService_ListPermissions + parameters: + - schema: + type: string + description: Page token to retrieve next page of results + name: page_token + in: query + - schema: + type: integer + format: int64 + description: Number of permissions to return per page (max 100) + name: page_size + in: query + - schema: + type: string + enum: + - SCALEKIT + - ENVIRONMENT + description: 'Filter permissions by type: ALL, SCALEKIT, or ENVIRONMENT, where SCALEKIT are predefined Scalekit permissions and ENVIRONMENT are custom permissions created in the environment, default is ALL' + name: type + in: query + responses: + '200': + description: Successfully retrieved the list of permissions. Returns a paginated list of permission objects with metadata and pagination tokens for navigation. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesListPermissionsResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const res = await scalekit.permission.listPermissions(); + - label: Python SDK + lang: python + source: res = scalekit_client.permissions.list_permissions() + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Permission().ListPermissions(ctx) + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: ListPermissionsResponse res = scalekitClient.permissions().listPermissions(); + post: + description: Creates a new permission that represents a specific action users can perform within the environment. Use this endpoint to define granular access controls for your RBAC system. You can provide a unique permission name following the format 'action:resource' (for example, 'read:documents', 'write:users') and an optional description explaining the permission's purpose. The permission name must be unique across the environment and follows alphanumeric naming conventions with colons and underscores. Returns the created permission object including system-generated ID and timestamps. + tags: + - Permissions + summary: Create new permission + operationId: RolesService_CreatePermission + responses: + '201': + description: Permission created successfully. Returns the complete permission object with system-generated ID, name, description, and timestamps. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesCreatePermissionResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + await scalekit.permission.createPermission({ + name: "read:users", + description: "Allows reading users" + }); + - label: Python SDK + lang: python + source: |- + from scalekit.v1.roles.roles_pb2 import CreatePermission + + permission = CreatePermission( + name="read:users", + description="Allows reading users" + ) + + scalekit_client.permissions.create_permission(permission=permission) + - label: Go SDK + lang: go + source: "resp, err := scalekitClient.Permission().CreatePermission(ctx, &rolesv1.CreatePermission{\n\n\tName: \"read:users\",\n\n\tDescription: \"Allows reading users\",\n\n})\nif err != nil { /* handle err */ }\n_ = resp" + - label: Java SDK + lang: java + source: |- + CreatePermissionResponse res = scalekitClient.permissions().createPermission( + CreatePermissionRequest.newBuilder() + .setPermission( + CreatePermission.newBuilder() + .setName("read:users") + .setDescription("Allows reading users") + .build() + ) + .build() + ); + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/v1rolesCreatePermission' + required: true + /api/v1/permissions/{permission_name}: + get: + description: Retrieves complete information for a specific permission by its unique name identifier. Use this endpoint to view permission details including description, creation time, and last update time. Provide the permission name in the path parameter following the format 'action:resource' (for example, 'read:documents'). This operation is useful for auditing permission definitions, understanding permission purposes, or verifying permission existence before assignment. Returns the complete permission object with all metadata and system-generated timestamps. + tags: + - Permissions + summary: Retrieve permission details + operationId: RolesService_GetPermission + parameters: + - schema: + type: string + description: Name of the permission + name: permission_name + in: path + required: true + responses: + '200': + description: Successfully retrieved permission details. Returns the complete permission object including name, description, creation time, and update time. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesGetPermissionResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const res = await scalekit.permission.getPermission("read:users"); + - label: Python SDK + lang: python + source: |- + res = scalekit_client.permissions.get_permission( + permission_name="read:users" + ) + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Permission().GetPermission(ctx, "read:users") + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: GetPermissionResponse res = scalekitClient.permissions().getPermission("read:users"); + put: + description: Modifies an existing permission's attributes including description and metadata. Use this endpoint to update permission descriptions or clarify permission purposes after creation. The permission is identified by its unique name in the path parameter, and only the fields you specify in the request body will be updated. Note that the permission name itself cannot be changed as it serves as the immutable identifier. This operation is useful for maintaining clear documentation of permission purposes or updating descriptions to reflect changes in system functionality. Returns the updated permission object with modified timestamps. + tags: + - Permissions + summary: Update permission details + operationId: RolesService_UpdatePermission + parameters: + - schema: + type: string + description: Name of the permission + name: permission_name + in: path + required: true + responses: + '200': + description: Permission updated successfully. Returns the modified permission object with updated description and timestamps. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesUpdatePermissionResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + await scalekit.permission.updatePermission("read:users", { + name: "read:users", + description: "Allows reading user resources" + }); + - label: Python SDK + lang: python + source: |- + from scalekit.v1.roles.roles_pb2 import CreatePermission + + scalekit_client.permissions.update_permission( + permission_name="read:users", + permission=CreatePermission( + name="read:users", + description="Allows reading user resources" + ) + ) + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Permission().UpdatePermission(ctx, "read:users", &rolesv1.CreatePermission{ + Name: "read:users", + Description: "Allows reading user resources", + }) + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: |- + UpdatePermissionResponse res = scalekitClient.permissions().updatePermission( + "read:users", + UpdatePermissionRequest.newBuilder() + .setPermission( + CreatePermission.newBuilder() + .setName("read:users") + .setDescription("Allows reading user resources") + .build() + ) + .build() + ); + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/v1rolesCreatePermission' + required: true + delete: + description: Permanently removes a permission from the environment using its unique name identifier. Use this endpoint when you need to clean up unused permissions or remove access controls that are no longer relevant. The permission is identified by its name in the path parameter following the format 'action:resource'. This operation cannot be undone, so ensure no active roles depend on the permission before deletion. If the permission is currently assigned to any roles, you may need to remove those assignments first or update the roles to use alternative permissions. Returns no content on successful deletion. + tags: + - Permissions + summary: Delete permission + operationId: RolesService_DeletePermission + parameters: + - schema: + type: string + description: Name of the permission + name: permission_name + in: path + required: true + responses: + '200': + description: Permission successfully deleted. No content returned. + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: await scalekit.permission.deletePermission("read:users"); + - label: Python SDK + lang: python + source: |- + scalekit_client.permissions.delete_permission( + permission_name="read:users" + ) + - label: Go SDK + lang: go + source: |- + err := scalekitClient.Permission().DeletePermission(ctx, "read:users") + if err != nil { /* handle err */ } + - label: Java SDK + lang: java + source: scalekitClient.permissions().deletePermission("read:users"); + /api/v1/roles: + get: + description: Retrieves a comprehensive list of all roles available within the specified environment including organization roles. Use this endpoint to view all role definitions, including custom roles and their configurations. You can optionally include permission details for each role to understand their capabilities. This is useful for role management, auditing organization access controls, or understanding the available access levels within the organization. + tags: + - Roles + summary: List all roles in environment + operationId: RolesService_ListRoles + parameters: + - schema: + type: string + description: 'Include additional data in the response. Valid values: ''permissions'' (direct permissions only), ''permissions:all'' (includes inherited permissions from role hierarchy)' + name: include + in: query + responses: + '200': + description: Successfully retrieved list of roles. Returns all roles with their metadata and optionally their permissions. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesListRolesResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const res = await scalekit.role.listRoles(); + - label: Python SDK + lang: python + source: res = scalekit_client.roles.list_roles() + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Role().ListRoles(ctx) + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: ListRolesResponse res = scalekitClient.roles().listRoles(); + post: + description: Creates a new role within the environment with specified permissions and metadata. Use this endpoint to define custom roles that can be assigned to users or groups. You can create hierarchical roles by extending existing roles, assign specific permissions, and configure display information. Roles are the foundation of your access control system and determine what actions users can perform. + tags: + - Roles + summary: Create new role in environment + operationId: RolesService_CreateRole + responses: + '201': + description: Role created successfully. Returns the complete role object with system-generated ID and timestamps. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesCreateRoleResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + await scalekit.role.createRole({ + name: "admin", + displayName: "Admin", + description: "Environment-level role", + extends: "base_role", // optional + permissions: ["read:users"] // optional + }); + - label: Python SDK + lang: python + source: |- + from scalekit.v1.roles.roles_pb2 import CreateRole + + role = CreateRole( + name="admin", + display_name="Admin", + description="Environment-level role", + extends="base_role", # optional + permissions=["read:users"] # optional + ) + + scalekit_client.roles.create_role(role=role) + - label: Go SDK + lang: go + source: "resp, err := scalekitClient.Role().CreateRole(ctx, &rolesv1.CreateRole{\n\n\tName: \"admin\",\n\n\tDisplayName: \"Admin\",\n\n\tDescription: \"Environment-level role\",\n\n\tExtends: proto.String(\"base_role\"), // optional\n\n\tPermissions: []string{\"read:users\"}, // optional\n\n})" + - label: Java SDK + lang: java + source: |- + CreateRoleResponse res = scalekitClient.roles().createRole( + CreateRoleRequest.newBuilder() + .setRole( + CreateRole.newBuilder() + .setName("admin") + .setDisplayName("Admin") + .setDescription("Environment-level role") + // .setExtends("base_role") // optional + // .addPermissions("read:users") // optional + .build() + ) + .build() + ); + requestBody: + content: + application/json: + schema: + description: Role configuration details including name, display name, description, permissions, and inheritance settings. + $ref: '#/components/schemas/v1rolesCreateRole' + examples: + - description: Can edit content + display_name: Content Editor + name: content_editor + permissions: + - read:content + - write:content + required: true + /api/v1/roles/default: + patch: + description: Updates the default creator and member roles for the current environment. Use this endpoint to configure which roles are automatically assigned to new users when they join the environment. You can specify role names for both creator and member default roles. The system will validate that the specified roles exist and update the environment settings accordingly. Returns the updated default role objects including their complete role information and permissions. + tags: + - Roles + summary: Set default creator and member roles + operationId: RolesService_UpdateDefaultRoles2 + responses: + '200': + description: Default roles updated successfully + content: + application/json: + schema: + $ref: '#/components/schemas/rolesUpdateDefaultRolesResponse' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/rolesUpdateDefaultRolesRequest' + required: true + /api/v1/roles/{role_name}: + get: + description: Retrieves complete information for a specific role including metadata and inheritance details (base role and dependent role count). Use this endpoint to audit role configuration and understand the role's place in the hierarchy. To view the role's permissions, use the ListRolePermissions endpoint. + tags: + - Roles + summary: Get role details + operationId: RolesService_GetRole + parameters: + - schema: + type: string + description: Unique name identifier of the role to retrieve. Must be alphanumeric with underscores, 1-64 characters. + name: role_name + in: path + required: true + - schema: + type: string + description: 'Include additional data in the response. Valid values: ''permissions'' (direct permissions only), ''permissions:all'' (includes inherited permissions from role hierarchy)' + name: include + in: query + responses: + '200': + description: Successfully retrieved role details. Returns the role object including metadata and inheritance details. Permissions are not included. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesGetRoleResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const res = await scalekit.role.getRole("admin"); + - label: Python SDK + lang: python + source: res = scalekit_client.roles.get_role(role_name="admin") + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Role().GetRole(ctx, "admin") + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: GetRoleResponse res = scalekitClient.roles().getRole("admin"); + put: + description: Modifies an existing role's properties including display name, description, permissions, and inheritance. Use this endpoint to update role metadata, change permission assignments, or modify role hierarchy. Only the fields you specify will be updated, leaving other properties unchanged. When updating permissions, the new list replaces all existing permissions for the role. + tags: + - Roles + summary: Update role information + operationId: RolesService_UpdateRole + parameters: + - schema: + type: string + description: Unique name identifier of the role to update. Must be alphanumeric with underscores, 1-64 characters. + name: role_name + in: path + required: true + responses: + '200': + description: Role updated successfully. Returns the modified role object with updated timestamps. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesUpdateRoleResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + await scalekit.role.updateRole("admin", { + displayName: "Admin (Updated)", + description: "Updated description" + }); + - label: Python SDK + lang: python + source: |- + from scalekit.v1.roles.roles_pb2 import UpdateRole + + scalekit_client.roles.update_role( + role_name="admin", + role=UpdateRole( + display_name="Admin (Updated)", + description="Updated description" + ) + ) + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Role().UpdateRole(ctx, "admin", &rolesv1.UpdateRole{ + DisplayName: "Admin (Updated)", + Description: "Updated description", + }) + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: |- + UpdateRoleResponse res = scalekitClient.roles().updateRole( + "admin", + UpdateRoleRequest.newBuilder() + .setRole( + UpdateRole.newBuilder() + .setDisplayName("Admin (Updated)") + .setDescription("Updated description") + .build() + ) + .build() + ); + requestBody: + content: + application/json: + schema: + description: Role fields to update. Only specified fields will be modified. + $ref: '#/components/schemas/v1rolesUpdateRole' + examples: + - description: Can edit and approve content + display_name: Senior Editor + required: true + delete: + description: Permanently removes a role from the environment and reassigns users who had that role to a different role. Use this endpoint when you need to clean up unused roles or restructure your access control system. The role cannot be deleted if it has dependent roles (roles that extend it) unless you specify a replacement role. If users are assigned to the role being deleted, you must provide a reassign_role_name to move those users to a different role before deletion can proceed. This action cannot be undone, so ensure no critical users depend on the role before deletion. + tags: + - Roles + summary: Delete role and reassign users + operationId: RolesService_DeleteRole + parameters: + - schema: + type: string + description: Unique name identifier of the role to delete. Must be alphanumeric with underscores, 1-64 characters. + name: role_name + in: path + required: true + - schema: + type: string + description: Role name to reassign users to when deleting this role + name: reassign_role_id + in: query + - schema: + type: string + description: Role name to reassign users to when deleting this role + name: reassign_role_name + in: query + responses: + '200': + description: Role successfully deleted and users reassigned. No content returned. + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + // Basic delete + await scalekit.role.deleteRole("admin"); + + // With reassignment + await scalekit.role.deleteRole("admin", "member"); + - label: Python SDK + lang: python + source: |- + # Basic delete + scalekit_client.roles.delete_role(role_name="admin") + + # With reassignment + scalekit_client.roles.delete_role( + role_name="admin", + reassign_role_name="member" + ) + - label: Go SDK + lang: go + source: |- + // Basic delete + err := scalekitClient.Role().DeleteRole(ctx, "admin") + if err != nil { /* handle err */ } + + // With reassignment + err = scalekitClient.Role().DeleteRole(ctx, "admin", "member") + - label: Java SDK + lang: java + source: |- + // Basic delete + scalekitClient.roles().deleteRole("admin"); + + // With reassignment + scalekitClient.roles().deleteRole("admin", "member"); + /api/v1/roles/{role_name}/dependents: + get: + description: Retrieves all roles that directly extend the specified base role through inheritance. Use this endpoint to understand the role hierarchy and identify which roles inherit permissions from a particular base role. Provide the base role name as a path parameter, and the response will include all dependent roles with their metadata and permission information. This operation is useful for auditing role inheritance relationships, understanding the impact of changes to base roles, or managing role hierarchies effectively. Returns a list of dependent role objects including their names, display names, descriptions, and permission details. + tags: + - Roles + summary: List dependent roles + operationId: RolesService_ListDependentRoles + parameters: + - schema: + type: string + description: Name of the base role + name: role_name + in: path + required: true + responses: + '200': + description: Successfully retrieved dependent roles. Returns a list of all roles that extend the specified base role, including their metadata and permission information. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesListDependentRolesResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const res = await scalekit.role.listDependentRoles("admin"); + - label: Python SDK + lang: python + source: res = scalekit_client.roles.list_dependent_roles(role_name="admin") + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Role().ListDependentRoles(ctx, "admin") + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: ListDependentRolesResponse res = scalekitClient.roles().listDependentRoles("admin"); + /api/v1/roles/{role_name}/permissions: + get: + description: Retrieves all permissions directly assigned to the specified role, excluding permissions inherited from base roles. Use this endpoint to view the explicit permission assignments for a role, which is useful for understanding direct role capabilities, auditing permission assignments, or managing role-permission relationships. Provide the role name as a path parameter, and the response will include only the permissions that are directly assigned to that role. This operation does not include inherited permissions from role hierarchies - use ListEffectiveRolePermissions to see the complete set of permissions including inheritance. Returns a list of permission objects with their names, descriptions, and assignment metadata. + tags: + - Roles + summary: List permissions for role + operationId: RolesService_ListRolePermissions + parameters: + - schema: + type: string + description: Name of the role + name: role_name + in: path + required: true + responses: + '200': + description: Successfully retrieved role permissions. Returns a list of all permissions directly assigned to the specified role, excluding inherited permissions. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesListRolePermissionsResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const res = await scalekit.permission.listRolePermissions("admin"); + - label: Python SDK + lang: python + source: res = scalekit_client.permissions.list_role_permissions(role_name="admin") + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Permission().ListRolePermissions(ctx, "admin") + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: ListRolePermissionsResponse res = scalekitClient.permissions().listRolePermissions("admin"); + post: + description: Adds one or more permissions to the specified role while preserving existing permission assignments. Use this endpoint to grant additional capabilities to a role without affecting its current permission set. Provide the role name as a path parameter and a list of permission names in the request body. The system will validate that all specified permissions exist in the environment and add them to the role. Existing permission assignments remain unchanged, making this operation safe for incremental permission management. This is useful for gradually expanding role capabilities or adding new permissions as your system evolves. Returns the updated list of all permissions now assigned to the role. + tags: + - Roles + summary: Add permissions to role + operationId: RolesService_AddPermissionsToRole + parameters: + - schema: + type: string + description: Name of the role + name: role_name + in: path + required: true + responses: + '200': + description: Permissions added to role successfully. Returns the complete list of all permissions now assigned to the role, including both existing and newly added permissions. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesAddPermissionsToRoleResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: await scalekit.permission.addPermissionsToRole("role_admin", ["perm.read", "perm.write"]); + - label: Python SDK + lang: python + source: |- + scalekit_client.permissions.add_permissions_to_role( + role_name="role_admin", + permission_names=["perm.read", "perm.write"] + ) + - label: Go SDK + lang: go + source: resp, err := scalekitClient.Permission().AddPermissionsToRole(ctx, "role_admin", []string{"perm.read", "perm.write"}) + - label: Java SDK + lang: java + source: |- + AddPermissionsToRoleResponse res = scalekitClient.permissions().addPermissionsToRole( + "role_admin", + AddPermissionsToRoleRequest.newBuilder() + .addPermissionNames("perm.read") + .addPermissionNames("perm.write") + .build() + ); + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RolesServiceAddPermissionsToRoleBody' + required: true + /api/v1/roles/{role_name}/permissions/{permission_name}: + delete: + description: Removes a specific permission from the specified role, revoking that capability from all users assigned to the role. Use this endpoint to restrict role capabilities or remove unnecessary permissions. Provide both the role name and permission name as path parameters. This operation only affects the direct permission assignment and does not impact permissions inherited from base roles. If the permission is inherited through role hierarchy, you may need to modify the base role instead. This is useful for fine-tuning role permissions, implementing least-privilege access controls, or removing deprecated permissions. Returns no content on successful removal. + tags: + - Roles + summary: Remove permission from role + operationId: RolesService_RemovePermissionFromRole + parameters: + - schema: + type: string + description: Name of the role + name: role_name + in: path + required: true + - schema: + type: string + description: Name of the permission to remove + name: permission_name + in: path + required: true + responses: + '200': + description: Permission removed from role successfully. No content returned. + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: await scalekit.permission.removePermissionFromRole("admin", "read:users"); + - label: Python SDK + lang: python + source: |- + scalekit_client.permissions.remove_permission_from_role( + role_name="admin", + permission_name="read:users" + ) + - label: Go SDK + lang: go + source: |- + err := scalekitClient.Permission().RemovePermissionFromRole(ctx, "admin", "read:users") + if err != nil { /* handle err */ } + - label: Java SDK + lang: java + source: scalekitClient.permissions().removePermissionFromRole("admin", "read:users"); + /api/v1/roles/{role_name}/permissions:all: + get: + description: Retrieves the complete set of effective permissions for a role, including both directly assigned permissions and permissions inherited from base roles through the role hierarchy. Use this endpoint to understand the full scope of capabilities available to users assigned to a specific role. Provide the role name as a path parameter, and the response will include all permissions that apply to the role, accounting for inheritance relationships. This operation is essential for auditing role capabilities, understanding permission inheritance, or verifying the complete access scope before role assignment. Returns a comprehensive list of permission names representing the full set of effective permissions for the specified role. + tags: + - Roles + summary: List effective permissions for role + operationId: RolesService_ListEffectiveRolePermissions + parameters: + - schema: + type: string + description: Name of the role + name: role_name + in: path + required: true + responses: + '200': + description: Successfully retrieved effective permissions. Returns the complete list of all permissions that apply to the role, including both direct assignments and inherited permissions from base roles. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesListEffectiveRolePermissionsResponse' + /api/v1/roles/{role_name}/users:count: + get: + description: Retrieves the total number of users currently assigned to the specified role within the environment. Use this endpoint to monitor role usage, enforce user limits, or understand the scope of role assignments. Provide the role's unique name as a path parameter, and the response will include the current user count for that role. This operation is read-only and does not modify any data or user assignments. The count reflects all users who have the role either directly assigned or inherited through organization membership. This information is useful for capacity planning, security auditing, or understanding the impact of role changes across your user base. + tags: + - Roles + summary: Retrieve user count for role + operationId: RolesService_GetRoleUsersCount + parameters: + - schema: + type: string + description: Unique name of the role + name: role_name + in: path + required: true + responses: + '200': + description: Successfully retrieved user count for the specified role. Returns the total number of users currently assigned to the role, including both direct assignments and inherited assignments. + content: + application/json: + schema: + $ref: '#/components/schemas/rolesGetRoleUsersCountResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const res = await scalekit.role.getRoleUsersCount("admin"); + - label: Python SDK + lang: python + source: res = scalekit_client.roles.get_role_users_count(role_name="admin") + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Role().GetRoleUsersCount(ctx, "admin") + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: GetRoleUsersCountResponse res = scalekitClient.roles().getRoleUsersCount("admin"); + /api/v1/roles:set_defaults: + patch: + description: Updates the default creator and member roles for the current environment. Use this endpoint to configure which roles are automatically assigned to new users when they join the environment. You can specify role names for both creator and member default roles. The system will validate that the specified roles exist and update the environment settings accordingly. Returns the updated default role objects including their complete role information and permissions. + tags: + - Roles + summary: Set default creator and member roles + operationId: RolesService_UpdateDefaultRoles + responses: + '200': + description: Default roles updated successfully + content: + application/json: + schema: + $ref: '#/components/schemas/rolesUpdateDefaultRolesResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + const res = await scalekit.role.updateDefaultRoles({ + defaultMemberRole: "member" + }); + - label: Python SDK + lang: python + source: |- + from scalekit.v1.roles.roles_pb2 import UpdateDefaultRolesRequest + + res = scalekit_client.roles.update_default_roles( + default_roles=UpdateDefaultRolesRequest( + default_member_role="member" + ) + ) + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Role().UpdateDefaultRoles(ctx, "member") + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: |- + UpdateDefaultRolesResponse res = scalekitClient.roles().updateDefaultRoles( + UpdateDefaultRolesRequest.newBuilder() + .setDefaultMemberRole("member") + .build() + ); + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/rolesUpdateDefaultRolesRequest' + required: true + /api/v1/sessions/{session_id}: + get: + description: Retrieves comprehensive details for a specific user session including authentication status, device information, and expiration timelines. Use this endpoint to fetch current session metadata for security audits, session validation, or to display session information in user account management interfaces. Returns all session properties including the user ID, authenticated organizations, device details with browser/OS information, IP address and geolocation, and all relevant timestamps (creation, last activity, idle expiration, absolute expiration, and actual expiration if applicable). + tags: + - Sessions + summary: Get session details + operationId: SessionService_GetSession + parameters: + - schema: + type: string + description: Unique identifier for the session. Must start with 'ses_' prefix. + name: session_id + in: path + required: true + responses: + '200': + description: Successfully retrieved session details + content: + application/json: + schema: + $ref: '#/components/schemas/sessionsSessionDetails' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const res = await scalekit.session.getSession("ses_123456789"); + - label: Python SDK + lang: python + source: res = scalekit_client.sessions.get_session(session_id="ses_123456789") + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Session().GetSession(ctx, "ses_123456789") + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: SessionDetails res = scalekitClient.sessions().getSession("ses_123456789"); + /api/v1/sessions/{session_id}/revoke: + post: + description: Immediately invalidates a specific user session by session ID, setting its status to 'revoked'. Once revoked, the session cannot be used for any future API requests or application access. Use this endpoint to implement session-level logout, force a user to reauthenticate on a specific device, or terminate suspicious sessions. The revocation is instantaneous and irreversible. Returns the revoked session details including the session ID, user ID, and the revocation timestamp. + tags: + - Sessions + summary: Revoke user session + operationId: SessionService_RevokeSession + parameters: + - schema: + type: string + description: Unique identifier for the session to revoke. Must start with 'ses_' prefix. + name: session_id + in: path + required: true + responses: + '200': + description: Successfully revoked the session. Returns the revoked session details + content: + application/json: + schema: + $ref: '#/components/schemas/sessionsRevokeSessionResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const res = await scalekit.session.revokeSession("ses_123456789"); + - label: Python SDK + lang: python + source: res = scalekit_client.sessions.revoke_session(session_id="ses_123456789") + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Session().RevokeSession(ctx, "ses_123456789") + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: RevokeSessionResponse res = scalekitClient.sessions().revokeSession("ses_123456789"); + /api/v1/users: + get: + description: Retrieves a paginated list of all users across your entire environment. Use this endpoint to view all users regardless of their organization memberships. This is useful for administrative purposes, user audits, or when you need to see all users in your Scalekit environment. Supports pagination for large user bases. + tags: + - Users + summary: List all users in environment + operationId: UserService_ListUsers + parameters: + - schema: + type: integer + format: int64 + description: Maximum number of organizations to return per page. Must be between 10 and 100 + name: page_size + in: query + - schema: + type: string + description: Pagination token from the previous response. Use to retrieve the next page of organizations + name: page_token + in: query + responses: + '200': + description: List of users. + content: + application/json: + schema: + $ref: '#/components/schemas/usersListUsersResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + const response = await scalekit.user.listUsers( + { pageSize: 100 }); + - label: Python SDK + lang: python + source: |- + # pass empty org to fetch all users in environment + resp,_ = scalekit_client.users.list_users(organization_id="", page_size=100) + - label: Go SDK + lang: go + source: 'all, err := scalekitClient.User().ListUsers(ctx, &scalekit.ListUsersOptions{PageSize: 100})' + - label: Java SDK + lang: java + source: |- + ListUsersRequest lur = ListUsersRequest. + newBuilder().setPageSize(100).build(); + ListUsersResponse allUsers = users.listUsers(lur); + /api/v1/users/{id}: + get: + description: Retrieves all details for a user by system-generated user ID or external ID. The response includes organization memberships and user metadata. + tags: + - Users + summary: Get user + operationId: UserService_GetUser + parameters: + - schema: + type: string + description: System-generated user ID + name: id + in: path + required: true + - schema: + type: string + description: Your application's unique identifier for this organization, used to link Scalekit with your system. + name: external_id + in: query + responses: + '200': + description: User details retrieved successfully. Returns full user object with system-generated fields and timestamps. + content: + application/json: + schema: + $ref: '#/components/schemas/usersGetUserResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const { user } = await scalekit.user.getUser("usr_123456"); + - label: Python SDK + lang: python + source: |- + resp = scalekit_client.users.get_user(user_id="usr_123456") + user = resp.user + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.User().GetUser(ctx, "usr_123456") + if err != nil { + // handle error + } + user := resp.User + - label: Java SDK + lang: java + source: |- + GetUserResponse resp = scalekitClient.users().getUser("usr_123456"); + User user = resp.getUser(); + delete: + description: Permanently removes a user from your environment and deletes all associated data. Use this endpoint when you need to completely remove a user account. This action deletes the user's profile, memberships, and all related data across all organizations. This operation cannot be undone, so use with caution. + tags: + - Users + summary: Delete user permanently + operationId: UserService_DeleteUser + parameters: + - schema: + type: string + description: System-generated user ID. Must start with 'usr_' (19-25 characters) + name: id + in: path + required: true + - schema: + type: string + description: External system identifier from connected directories. Must match existing records + name: external_id + in: query + responses: + '200': + description: User successfully deleted. No content returned + content: + application/json: + schema: {} + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: await scalekit.user.deleteUser("usr_123"); + - label: Python SDK + lang: python + source: |- + scalekit_client.users.delete_user(organization_id="org_123", + user_id="usr_123") + - label: Go SDK + lang: go + source: |- + if err := scalekitClient.User().DeleteUser(ctx, + "usr_123"); err != nil { + panic(err) + } + - label: Java SDK + lang: java + source: users.deleteUser("usr_123"); + patch: + description: Modifies user account information including profile details, metadata, and external ID. Use this endpoint to update a user's personal information, contact details, or custom metadata. You can update the user's profile, phone number, and metadata fields. Note that fields like user ID, email address, environment ID, and creation time cannot be modified. + tags: + - Users + summary: Update user information + operationId: UserService_UpdateUser + parameters: + - schema: + type: string + description: System-generated user ID. Must start with 'usr_' and be 19-25 characters long. + name: id + in: path + required: true + - schema: + type: string + description: Your application's unique identifier for this organization, used to link Scalekit with your system. + name: external_id + in: query + responses: + '200': + description: User updated successfully. Returns the modified user object with updated timestamps. + content: + application/json: + schema: + $ref: '#/components/schemas/usersUpdateUserResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: "await scalekit.user.updateUser(\"usr_123\", {\n\tuserProfile: {\n\t\tfirstName: \"John\",\n\t\tlastName: \"Smith\",\n\t},\n\tmetadata: {\n\t\tdepartment: \"sales\",\n\t},\n});" + - label: Python SDK + lang: python + source: |- + import os + from scalekit import ScalekitClient + from scalekit.v1.users.users_pb2 import UpdateUser + from scalekit.v1.commons.commons_pb2 import UserProfile + scalekit_client = ScalekitClient( + env_url=os.getenv("SCALEKIT_ENV_URL"), + client_id=os.getenv("SCALEKIT_CLIENT_ID"), + client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"), + ) + update_user = UpdateUser( + user_profile=UserProfile( + first_name="John", + last_name="Smith" + ), + metadata={"department": "sales"} + ) + scalekit_client.users.update_user(organization_id="org_123", + user=update_user) + - label: Go SDK + lang: go + source: |- + upd := &usersv1.UpdateUser{ + UserProfile: &usersv1.UpdateUserProfile{ + FirstName: "John", + LastName: "Smith", + }, + Metadata: map[string]string{ + "department": "sales", + }, + } + scalekitClient.User().UpdateUser(ctx, "usr_123", upd) + - label: Java SDK + lang: java + source: |- + UpdateUser upd = UpdateUser.newBuilder() + .setUserProfile( + UpdateUserProfile.newBuilder() + .setFirstName("John") + .setLastName("Smith") + .build()) + .putMetadata("department", "sales") + .build(); + UpdateUserRequest updReq = UpdateUserRequest. + newBuilder().setUser(upd).build(); + users.updateUser("usr_123", updReq); + requestBody: + content: + application/json: + schema: + description: User fields to update. Only specified fields will be modified. Required fields must be provided if being changed. + $ref: '#/components/schemas/v1usersUpdateUser' + examples: + - firstName: John + lastName: Doe + required: true + /api/v1/users/{user_id}/sessions: + get: + description: Retrieves a paginated list of all sessions associated with a specific user across all devices and browsers. Use this endpoint to audit user activity, display all active sessions in account management interfaces, or verify user authentication status across devices. Supports filtering by session status (active, expired, revoked, logout) and time range (creation date). Returns session details for each session including device information, IP address, geolocation, and current status. The response includes pagination metadata (page tokens and total count) to handle large session lists efficiently. + tags: + - Sessions + summary: List user sessions + operationId: SessionService_GetUserSessions + parameters: + - schema: + type: string + description: Unique identifier for the user whose sessions to retrieve. Must start with 'usr_' prefix. + name: user_id + in: path + required: true + - schema: + type: integer + format: int64 + description: Maximum number of sessions to return in a single page. Optional parameter. If not specified, defaults to a server-defined limit. Use smaller values for faster responses, larger values for fewer requests. + name: page_size + in: query + - schema: + type: string + description: Pagination token from the previous response for retrieving the next page of results. Leave empty for the first page. Use the next_page_token from a previous response to fetch subsequent pages. + name: page_token + in: query + - schema: + type: array + items: + type: string + style: form + explode: true + description: 'Filter sessions by one or more status values. Possible values: ''active'', ''expired'', ''revoked'', ''logout''. Leave empty to include all statuses. Multiple values use OR logic (e.g., status=[''active'', ''expired''] returns sessions that are either active OR expired).' + name: filter.status + in: query + - schema: + type: string + format: date-time + description: Filter to include only sessions created on or after this timestamp. Optional. Uses RFC 3339 format. Useful for querying sessions within a specific time window. + name: filter.start_time + in: query + - schema: + type: string + format: date-time + description: Filter to include only sessions created on or before this timestamp. Optional. Uses RFC 3339 format. Must be after start_time if both are specified. + name: filter.end_time + in: query + responses: + '200': + description: Successfully retrieved user sessions. Returns a list of sessions with pagination information + content: + application/json: + schema: + $ref: '#/components/schemas/sessionsUserSessionDetails' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + // Basic usage + const res = await scalekit.session.getUserSessions("user_123"); + + // With pagination and filtering + const res = await scalekit.session.getUserSessions("user_123", { + pageSize: 10, + pageToken: "next_page_token", + filter: { + status: ["ACTIVE"], + startTime: new Date("2024-01-01"), + endTime: new Date("2024-12-31") + } + }); + - label: Python SDK + lang: python + source: |- + # Basic usage + res = scalekit_client.sessions.get_user_sessions(user_id="user_123") + + # With pagination and filtering + from google.protobuf.timestamp_pb2 import Timestamp + from datetime import datetime + + start_time = Timestamp() + start_time.FromDatetime(datetime(2024, 1, 1)) + end_time = Timestamp() + end_time.FromDatetime(datetime(2024, 12, 31)) + + filter_obj = scalekit_client.sessions.create_session_filter( + status=["ACTIVE"], start_time=start_time, end_time=end_time + ) + res = scalekit_client.sessions.get_user_sessions( + user_id="user_123", page_size=10, page_token="next_page_token", filter=filter_obj + ) + - label: Go SDK + lang: go + source: |- + // Basic usage + resp, err := scalekitClient.Session().GetUserSessions(ctx, "user_123", 0, "", nil) + if err != nil { /* handle err */ } + + // With pagination and filtering + // import "time", sessionsv1 "...", "google.golang.org/protobuf/types/known/timestamppb" + startTime, _ := time.Parse(time.RFC3339, "2024-01-01T00:00:00Z") + endTime, _ := time.Parse(time.RFC3339, "2024-12-31T23:59:59Z") + filter := &sessionsv1.UserSessionFilter{ + Status: []string{"ACTIVE"}, + StartTime: timestamppb.New(startTime), + EndTime: timestamppb.New(endTime), + } + resp, err := scalekitClient.Session().GetUserSessions(ctx, "user_123", 10, "next_page_token", filter) + if err != nil { /* handle err */ } + - label: Java SDK + lang: java + source: |- + // Basic usage + UserSessionDetails res = scalekitClient.sessions().getUserSessions("user_123", null, null, null); + + // With pagination and filtering + // import UserSessionFilter, Timestamp, Instant + UserSessionFilter filter = UserSessionFilter.newBuilder() + .addStatus("ACTIVE") + .setStartTime(Timestamp.newBuilder().setSeconds(Instant.parse("2024-01-01T00:00:00Z").getEpochSecond()).build()) + .setEndTime(Timestamp.newBuilder().setSeconds(Instant.parse("2024-12-31T23:59:59Z").getEpochSecond()).build()) + .build(); + UserSessionDetails res = scalekitClient.sessions().getUserSessions("user_123", 10, "next_page_token", filter); + /api/v1/users/{user_id}/sessions/revoke: + post: + description: Immediately invalidates all active sessions for a specific user across all devices and browsers, setting their status to 'revoked'. Use this endpoint to implement global logout functionality, force re-authentication after security incidents, or terminate all sessions following a password reset or credential compromise. Only active sessions are revoked; already expired, logout, or previously revoked sessions remain unchanged. The revocation is atomic and instantaneous. Returns a list of all revoked sessions with their details and a total count of sessions revoked. + tags: + - Sessions + summary: Revoke all user sessions + operationId: SessionService_RevokeAllUserSessions + parameters: + - schema: + type: string + description: Unique identifier for the user whose all sessions will be revoked. Must start with 'usr_' prefix. + name: user_id + in: path + required: true + responses: + '200': + description: Successfully revoked all user sessions. Returns the list of revoked sessions and total count + content: + application/json: + schema: + $ref: '#/components/schemas/sessionsRevokeAllUserSessionsResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const res = await scalekit.session.revokeAllUserSessions("user_123"); + - label: Python SDK + lang: python + source: res = scalekit_client.sessions.revoke_all_user_sessions(user_id="user_123") + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.Session().RevokeAllUserSessions(ctx, "user_123") + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: RevokeAllUserSessionsResponse res = scalekitClient.sessions().revokeAllUserSessions("user_123"); + /api/v1/users:search: + get: + description: Searches for users across the entire environment by email address, user ID, or external ID. The query must be at least 3 characters and is case-insensitive. Returns a paginated list of matching users with up to 30 results per page. Use the next_page_token from the response to retrieve subsequent pages. + tags: + - Users + summary: Search users + operationId: UserService_SearchUsers + parameters: + - schema: + type: string + minLength: 3 + maxLength: 100 + description: Search term to match against user email, IDs, or external IDs. Must be at least 3 characters. Case insensitive. + name: query + in: query + required: true + - schema: + type: integer + format: int64 + minimum: 1 + maximum: 30 + description: Maximum number of users to return per page. Value must be between 1 and 30. + name: page_size + in: query + - schema: + type: string + description: Token from a previous response for pagination. Provide this to retrieve the next page of results. + name: page_token + in: query + responses: + '200': + description: Matching users returned; includes pagination cursors for navigating large result sets. + content: + application/json: + schema: + $ref: '#/components/schemas/usersSearchUsersResponse' + '400': + description: Bad Request - query must be at least 3 characters and no more than 100 characters. + content: + application/json: + schema: {} + /api/v1/webauthn/credentials: + get: + description: Retrieves all registered passkeys for the current user, including device information, creation timestamps, and display names. Use this to show users their registered authenticators. + tags: + - Passkeys + summary: List user's passkeys + operationId: WebAuthnService_ListCredentials + parameters: + - schema: + type: string + description: User ID to list credentials for (optional, current user if not provided) + name: user_id + in: query + responses: + '200': + description: List of passkeys with metadata + content: + application/json: + schema: + $ref: '#/components/schemas/webauthnListCredentialsResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const res = await scalekit.webauthn.listCredentials("user_123"); + - label: Python SDK + lang: python + source: res = scalekit_client.webauthn.list_credentials(user_id="user_123") + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.WebAuthn().ListCredentials(ctx, "user_123") + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: ListCredentialsResponse res = scalekitClient.webauthn().listCredentials("user_123"); + /api/v1/webauthn/credentials/{credential_id}: + delete: + description: Deletes a specific passkey credential for the current user. After removal, the authenticator can no longer be used for authentication. + tags: + - Passkeys + summary: Remove a passkey + operationId: WebAuthnService_DeleteCredential + parameters: + - schema: + type: string + description: The credential ID to delete + name: credential_id + in: path + required: true + responses: + '200': + description: Passkey successfully deleted + content: + application/json: + schema: + $ref: '#/components/schemas/webauthnDeleteCredentialResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: const res = await scalekit.webauthn.deleteCredential("wac_123"); + - label: Python SDK + lang: python + source: res = scalekit_client.webauthn.delete_credential(credential_id="wac_123") + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.WebAuthn().DeleteCredential(ctx, "wac_123") + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: DeleteCredentialResponse res = scalekitClient.webauthn().deleteCredential("wac_123"); + patch: + description: Updates the display name of a passkey credential to help users identify their authenticators. Only the display name can be modified. + tags: + - Passkeys + summary: Rename a passkey + operationId: WebAuthnService_UpdateCredential + parameters: + - schema: + type: string + description: The credential ID to update + name: credential_id + in: path + required: true + responses: + '200': + description: Passkey successfully updated with new name + content: + application/json: + schema: + $ref: '#/components/schemas/webauthnUpdateCredentialResponse' + x-codeSamples: + - label: Node.js SDK + lang: javascript + source: |- + const res = await scalekit.webauthn.updateCredential( + "wac_123", + "Work Laptop Passkey" + ); + - label: Python SDK + lang: python + source: |- + res = scalekit_client.webauthn.update_credential( + credential_id="wac_123", + display_name="Work Laptop Passkey" + ) + - label: Go SDK + lang: go + source: |- + resp, err := scalekitClient.WebAuthn().UpdateCredential( + ctx, + "wac_123", + "Work Laptop Passkey", + ) + if err != nil { /* handle err */ } + _ = resp + - label: Java SDK + lang: java + source: |- + UpdateCredentialResponse res = scalekitClient.webauthn() + .updateCredential("wac_123", "Work Laptop Passkey"); + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/WebAuthnServiceUpdateCredentialBody' + required: true +webhooks: + organization.created: + post: + summary: Organization Created + description: Triggered when a new organization is created in Scalekit + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_1234567890 + type: organization.created + object: Organization + occurred_at: '2024-01-15T10:30:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_1234567890 + data: + create_time: '2025-12-09T09:25:02.02Z' + display_name: AcmeCorp + external_id: org_external_123 + id: org_1234567890 + metadata: null + region_code: US + update_time: '2025-12-09T09:25:02.025330364Z' + settings: + features: + - enabled: true + name: sso + - enabled: false + name: dir_sync + display_name: Organization Created + responses: + '200': + description: Webhook received successfully + organization.updated: + post: + summary: Organization Updated + description: Triggered when an organization is updated + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_2345678901 + type: organization.updated + object: Organization + occurred_at: '2024-01-15T10:35:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_1234567890 + data: + create_time: '2025-12-09T09:25:02.02Z' + display_name: AcmeCorp + external_id: org_external_123 + id: org_1234567890 + metadata: null + region_code: US + update_time: '2025-12-09T09:25:02.025330364Z' + settings: + features: + - enabled: true + name: sso + - enabled: false + name: dir_sync + display_name: Organization Updated + responses: + '200': + description: Webhook received successfully + organization.deleted: + post: + summary: Organization Deleted + description: Triggered when an organization is deleted + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_3456789012 + type: organization.deleted + object: Organization + occurred_at: '2024-01-15T10:40:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_1234567890 + data: + create_time: '2025-12-09T09:25:02.02Z' + deleted_at: '2025-12-09T10:25:45.337417Z' + display_name: AcmeCorp + external_id: org_external_123 + id: org_1234567890 + metadata: null + region_code: US + update_time: '2025-12-09T09:25:02.025330364Z' + settings: + features: + - enabled: true + name: sso + - enabled: false + name: dir_sync + display_name: Organization Deleted + responses: + '200': + description: Webhook received successfully + user.signup: + post: + summary: User Signup + description: Triggered when a user signs up to create a new organization + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_1234567890 + type: user.signup + object: OrgMembership + occurred_at: '2024-01-15T10:30:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_102690563312124938 + data: + organization: + id: org_102690563312124938 + create_time: '2025-12-09T10:19:05.48Z' + display_name: '' + external_id: null + metadata: null + region_code: US + update_time: '2025-12-09T12:04:41.386974738Z' + settings: + features: + - enabled: true + name: sso + - enabled: true + name: dir_sync + user: + create_time: '2025-12-09T12:04:41.39Z' + email: amit.ash1996@gmail.com + external_id: '' + id: usr_102701193205121289 + metadata: {} + update_time: '2025-12-09T12:04:41.391988278Z' + user_profile: + custom_attributes: null + email_verified: true + external_identities: null + family_name: doe + gender: '' + given_name: John + groups: null + id: usp_102701193205186825 + locale: '' + metadata: {} + name: John Doe + phone_number: '' + phone_number_verified: false + picture: https://lh3.googleusercontent.com/a/abcdef + preferred_username: '' + display_name: User Signup + responses: + '200': + description: Webhook received successfully + user.login: + post: + summary: User Login + description: Triggered when a user logs in and a session is created + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_102701193859432713 + type: user.login + object: User + occurred_at: '2025-12-09T12:04:41.781873312Z' + environment_id: env_96736846679245078 + organization_id: org_102701193188409609 + data: + user: + create_time: '2025-12-09T12:04:41.39Z' + email: john.doe@acmecorp.com + external_id: ext_123456789 + id: usr_123456789 + last_login_time: '2025-12-09T12:04:41.48Z' + metadata: {} + update_time: '2025-12-09T12:04:41.391988Z' + user_profile: + custom_attributes: null + email_verified: true + external_identities: + - connection_id: conn_97896332307464201 + connection_provider: GOOGLE + connection_type: OAUTH + connection_user_id: '105055379523565727691' + created_time: '2025-12-09T12:04:41.47Z' + is_social: true + last_login_time: '2025-12-09T12:04:41.469311Z' + last_synced_time: '2025-12-09T12:04:41.469311Z' + family_name: Doe + gender: '' + given_name: John + groups: null + id: usp_102701193205186825 + locale: '' + metadata: {} + name: John Doe + phone_number: '' + phone_number_verified: false + picture: https://lh3.googleusercontent.com/a/abcdef + preferred_username: '' + user_session: + absolute_expires_at: '2026-01-08T12:04:41.737394Z' + authenticated_organizations: + - org_102701193188409609 + created_at: '2025-12-09T12:04:41.48Z' + expired_at: null + idle_expires_at: '2025-12-16T12:04:41.737395Z' + last_active_at: '2025-12-09T12:04:41.747206Z' + logout_at: null + organization_id: org_102701193188409609 + session_id: ses_102701193356116233 + status: ACTIVE + updated_at: '2025-12-09T12:04:41.748512Z' + user_id: usr_102701193205121289 + device: + browser: Chrome + browser_version: 142.0.0.0 + device_type: Desktop + ip: 152.59.144.211 + location: + city: Patna + latitude: '25.594095' + longitude: '85.137564' + region: IN + region_subdivision: INBR + os: macOS + os_version: 10.15.7 + user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36 + display_name: User Login + responses: + '200': + description: Webhook received successfully + user.logout: + post: + summary: User Logout + description: Triggered when a user's session is terminated + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_102708230123160586 + type: user.logout + object: User + occurred_at: '2025-12-09T13:14:35.722070822Z' + environment_id: env_96736846679245078 + organization_id: org_102701193188409609 + data: + user: + create_time: '2025-12-09T12:04:41.39Z' + email: john.doe@acmecorp.com + external_id: ext_123456789 + id: usr_123456789 + last_login_time: '2025-12-09T12:04:41.48Z' + metadata: {} + update_time: '2025-12-09T12:04:41.391988Z' + user_profile: + custom_attributes: null + email_verified: true + external_identities: + - connection_id: conn_97896332307464201 + connection_provider: GOOGLE + connection_type: OAUTH + connection_user_id: '105055379523565727691' + created_time: '2025-12-09T12:04:41.47Z' + is_social: true + last_login_time: '2025-12-09T12:04:41.469311Z' + last_synced_time: '2025-12-09T12:04:41.469311Z' + family_name: Doe + gender: '' + given_name: John + groups: null + id: usp_102701193205186825 + locale: '' + metadata: {} + name: John Doe + phone_number: '' + phone_number_verified: false + picture: https://lh3.googleusercontent.com/a/abcdef + preferred_username: '' + user_session: + absolute_expires_at: '2026-01-08T12:04:41.737394Z' + authenticated_organizations: + - org_102701193188409609 + created_at: '2025-12-09T12:04:41.48Z' + expired_at: null + idle_expires_at: '2025-12-16T12:04:41.737395Z' + last_active_at: '2025-12-09T12:04:41.747206Z' + logout_at: null + organization_id: org_102701193188409609 + session_id: ses_102701193356116233 + status: ACTIVE + updated_at: '2025-12-09T12:04:41.748512Z' + user_id: usr_102701193205121289 + device: + browser: Chrome + browser_version: 142.0.0.0 + device_type: Desktop + ip: 152.59.144.211 + location: + city: Patna + latitude: '25.594095' + longitude: '85.137564' + region: IN + region_subdivision: INBR + os: macOS + os_version: 10.15.7 + user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36 + display_name: User Logout + responses: + '200': + description: Webhook received successfully + user.organization_invitation: + post: + summary: User Organization Invitation + description: Triggered when a user is invited to join an organization + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_4567890123 + type: user.organization_invitation + object: OrgMembership + occurred_at: '2024-01-15T11:00:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_102690563312124938 + data: + organization: + id: org_102690563312124938 + create_time: '2025-12-09T10:19:05.48Z' + display_name: Acme Corp + external_id: org_external_123 + metadata: null + region_code: US + update_time: '2025-12-09T12:04:41.386974738Z' + settings: + features: + - enabled: true + name: sso + - enabled: true + name: dir_sync + user: + create_time: '2025-12-09T12:04:41.39Z' + email: john.doe@acmecorp.com + external_id: ext_123456789 + id: usr_123456789 + metadata: {} + update_time: '2025-12-09T12:04:41.391988Z' + user_profile: + custom_attributes: null + email_verified: true + external_identities: + - connection_id: conn_97896332307464201 + connection_provider: GOOGLE + connection_type: OAUTH + connection_user_id: '105055379523565727691' + created_time: '2025-12-09T12:04:41.47Z' + is_social: true + last_login_time: '2025-12-09T12:04:41.469311Z' + last_synced_time: '2025-12-09T12:04:41.469311Z' + family_name: Doe + gender: '' + given_name: John + groups: null + id: usp_102701193205186825 + locale: '' + metadata: {} + name: John Doe + phone_number: '' + phone_number_verified: false + picture: https://lh3.googleusercontent.com/a/abcdef + preferred_username: '' + display_name: User Organization Invitation + responses: + '200': + description: Webhook received successfully + user.organization_membership_created: + post: + summary: User Organization Membership Created + description: Triggered when a user joins an organization + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_5678901234 + type: user.organization_membership_created + object: OrgMembership + occurred_at: '2024-01-15T11:05:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_102690563312124938 + data: + organization: + id: org_102690563312124938 + create_time: '2025-12-09T10:19:05.48Z' + display_name: Acme Corp + external_id: org_external_123 + metadata: null + region_code: US + update_time: '2025-12-09T12:04:41.386974738Z' + settings: + features: + - enabled: true + name: sso + - enabled: true + name: dir_sync + user: + create_time: '2025-12-09T12:04:41.39Z' + email: john.doe@acmecorp.com + external_id: ext_123456789 + id: usr_123456789 + metadata: {} + update_time: '2025-12-09T12:04:41.391988Z' + user_profile: + custom_attributes: null + email_verified: true + external_identities: + - connection_id: conn_97896332307464201 + connection_provider: GOOGLE + connection_type: OAUTH + connection_user_id: '105055379523565727691' + created_time: '2025-12-09T12:04:41.47Z' + is_social: true + last_login_time: '2025-12-09T12:04:41.469311Z' + last_synced_time: '2025-12-09T12:04:41.469311Z' + family_name: Doe + gender: '' + given_name: John + groups: null + id: usp_102701193205186825 + locale: '' + metadata: {} + name: John Doe + phone_number: '' + phone_number_verified: false + picture: https://lh3.googleusercontent.com/a/abcdef + preferred_username: '' + display_name: User Organization Membership Created + responses: + '200': + description: Webhook received successfully + user.organization_membership_deleted: + post: + summary: User Organization Membership Deleted + description: Triggered when a user's membership in an organization is removed or deleted + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_9012345678 + type: user.organization_membership_deleted + object: OrgMembership + occurred_at: '2024-01-15T11:10:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_102690563312124938 + data: + organization: + id: org_102690563312124938 + create_time: '2025-12-09T10:19:05.48Z' + display_name: Acme Corp + external_id: org_external_123 + metadata: null + region_code: US + update_time: '2025-12-09T12:04:41.386974738Z' + settings: + features: + - enabled: true + name: sso + - enabled: true + name: dir_sync + user: + create_time: '2025-12-09T12:04:41.39Z' + email: john.doe@acmecorp.com + external_id: ext_123456789 + id: usr_123456789 + metadata: {} + update_time: '2025-12-09T12:04:41.391988Z' + user_profile: + custom_attributes: null + email_verified: true + external_identities: + - connection_id: conn_97896332307464201 + connection_provider: GOOGLE + connection_type: OAUTH + connection_user_id: '105055379523565727691' + created_time: '2025-12-09T12:04:41.47Z' + is_social: true + last_login_time: '2025-12-09T12:04:41.469311Z' + last_synced_time: '2025-12-09T12:04:41.469311Z' + raw_attributes: '{}' + updated_time: '2025-12-09T12:04:41.473087Z' + family_name: Doe + gender: '' + given_name: John + locale: '' + metadata: {} + name: John Doe + phone_number: '' + phone_number_verified: false + picture: https://lh3.googleusercontent.com/a/abcdef + preferred_username: '' + display_name: User Organization Membership Deleted + responses: + '200': + description: Webhook received successfully + user.organization_membership_updated: + post: + summary: User Organization Membership Updated + description: Triggered when a user's organization membership is updated, e.g., change of user's role in an organization + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_6789012345 + type: user.organization_membership_updated + object: OrgMembership + occurred_at: '2024-01-15T11:10:00.123456789Z' + environment_id: env_1234567890 + organization_id: org_102690563312124938 + data: + organization: + id: org_102690563312124938 + create_time: '2025-12-09T10:19:05.48Z' + display_name: Acme Corp + external_id: org_external_123 + metadata: null + region_code: US + update_time: '2025-12-09T12:04:41.386974738Z' + settings: + features: + - enabled: true + name: sso + - enabled: true + name: dir_sync + user: + create_time: '2025-12-09T12:04:41.39Z' + email: john.doe@acmecorp.com + external_id: ext_123456789 + id: usr_123456789 + metadata: {} + update_time: '2025-12-09T12:04:41.391988Z' + user_profile: + custom_attributes: null + email_verified: true + external_identities: + - connection_id: conn_97896332307464201 + connection_provider: GOOGLE + connection_type: OAUTH + connection_user_id: '105055379523565727691' + created_time: '2025-12-09T12:04:41.47Z' + is_social: true + last_login_time: '2025-12-09T12:04:41.469311Z' + last_synced_time: '2025-12-09T12:04:41.469311Z' + raw_attributes: '{}' + updated_time: '2025-12-09T12:04:41.473087Z' + family_name: Doe + gender: '' + given_name: John + locale: '' + metadata: {} + name: John Doe + phone_number: '' + phone_number_verified: false + picture: https://lh3.googleusercontent.com/a/abcdef + preferred_username: '' + display_name: User Organization Membership Updated + responses: + '200': + description: Webhook received successfully + organization.directory_enabled: + post: + summary: Directory Enabled + description: Triggered when a directory sync is enabled + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_55136848686613000 + type: organization.directory_enabled + object: Directory + occurred_at: '2025-01-15T08:55:22.802860294Z' + environment_id: env_27758032200925221 + organization_id: org_55135410258444802 + data: + directory_type: SCIM + enabled: true + id: dir_55135622825771522 + organization_id: org_55135410258444802 + provider: OKTA + updated_at: '2025-01-15T08:55:22.792993454Z' + display_name: Directory Enabled + responses: + '200': + description: Webhook received successfully + organization.directory_disabled: + post: + summary: Directory Disabled + description: Triggered when a directory sync is disabled + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_53891640779079756 + type: organization.directory_disabled + object: Directory + occurred_at: '2025-01-06T18:45:21.057814Z' + environment_id: env_53814739859406915 + organization_id: org_53879494091473415 + data: + directory_type: SCIM + enabled: false + id: dir_53879621145330183 + organization_id: org_53879494091473415 + provider: OKTA + updated_at: '2025-01-06T18:45:21.04978184Z' + display_name: Directory Disabled + responses: + '200': + description: Webhook received successfully + organization.directory.user_created: + post: + summary: Directory User Created + description: Triggered when a new directory user is created + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_53891546994442316 + type: organization.directory.user_created + object: DirectoryUser + occurred_at: '2025-01-06T18:44:25.153954Z' + environment_id: env_53814739859406915 + organization_id: org_53879494091473415 + data: + active: true + cost_center: QAUZJUHSTYCN + custom_attributes: + mobile_phone_number: 1-579-4072 + department: HNXJPGISMIFN + division: MJFUEYJOKICN + dp_id: + email: flavio@runolfsdottir.co.duk + employee_id: AWNEDTILGaIZN + family_name: Jaquelin + given_name: Dayton + groups: + - id: dirgroup_12312312312312 + name: Group Name + id: diruser_53891546960887884 + language: se + locale: LLWLEWESPLDC + name: QDRGUZZDYMFU + nickname: DTUODYKGFPPC + organization: AUIITQVUQGVH + organization_id: org_53879494091473415 + phone_number: 1-579-4072 + preferred_username: kuntala1233a + profile: YMIUQUHKGVAX + raw_attributes: {} + title: FKQBHCWJXZSC + user_type: RBQFJSQEFAEH + zoneinfo: America/Araguaina + roles: + - role_name: billing_admin + display_name: Directory User Created + responses: + '200': + description: Webhook received successfully + organization.directory.user_updated: + post: + summary: Directory User Updated + description: Triggered when a directory user is updated + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_53891546994442317 + type: organization.directory.user_updated + object: DirectoryUser + occurred_at: '2025-01-06T18:44:25.153954Z' + environment_id: env_53814739859406915 + organization_id: org_53879494091473415 + data: + id: diruser_12312312312312 + organization_id: org_53879494091473415 + dp_id: + preferred_username: + email: john.doe@example.com + active: true + name: John Doe + roles: + - role_name: billing_admin + groups: + - id: dirgroup_12312312312312 + name: Group Name + given_name: John + family_name: Doe + nickname: Jhonny boy + picture: https://image.com/profile.jpg + phone_number: '1234567892' + address: + postal_code: '64112' + state: Missouri + formatted: 123, Oxford Lane, Kansas City, Missouri, 64112 + custom_attributes: + attribute1: value1 + attribute2: value2 + raw_attributes: {} + display_name: Directory User Updated + responses: + '200': + description: Webhook received successfully + organization.directory.user_deleted: + post: + summary: Directory User Deleted + description: Triggered when a directory user is deleted + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_53891546994442318 + type: organization.directory.user_deleted + object: DirectoryUser + occurred_at: '2025-01-06T18:44:25.153954Z' + environment_id: env_53814739859406915 + organization_id: org_53879494091473415 + data: + id: diruser_12312312312312 + organization_id: org_12312312312312 + dp_id: + email: john.doe@example.com + display_name: Directory User Deleted + responses: + '200': + description: Webhook received successfully + organization.directory.group_created: + post: + summary: Directory Group Created + description: Triggered when a new directory group is created + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_38862741515010639 + type: organization.directory.group_created + object: DirectoryGroup + occurred_at: '2024-09-25T02:26:39.036398577Z' + environment_id: env_32080745237316098 + organization_id: org_38609339635728478 + data: + directory_id: dir_38610496391217780 + display_name: Avengers + external_id: null + id: dirgroup_38862741498233423 + organization_id: org_38609339635728478 + raw_attributes: {} + display_name: Directory Group Created + responses: + '200': + description: Webhook received successfully + organization.directory.group_updated: + post: + summary: Directory Group Updated + description: Triggered when a directory group is updated + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_38864948910162368 + type: organization.directory.group_updated + object: DirectoryGroup + occurred_at: '2024-09-25T02:48:34.745030921Z' + environment_id: env_32080745237316098 + organization_id: org_38609339635728478 + data: + directory_id: dir_38610496391217780 + display_name: Avengers + external_id: + id: dirgroup_38862741498233423 + organization_id: org_38609339635728478 + raw_attributes: {} + display_name: Directory Group Updated + responses: + '200': + description: Webhook received successfully + organization.directory.group_deleted: + post: + summary: Directory Group Deleted + description: Triggered when a directory group is deleted + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_40650399597723966 + type: organization.directory.group_deleted + object: DirectoryGroup + occurred_at: '2024-10-07T10:25:26.289331747Z' + environment_id: env_12205603854221623 + organization_id: org_39802449573184223 + data: + directory_id: dir_39802485862301855 + display_name: Admins + dp_id: 7c66a173-79c6-4270-ac78-8f35a8121e0a + id: dirgroup_40072007005503806 + organization_id: org_39802449573184223 + raw_attributes: {} + display_name: Directory Group Deleted + responses: + '200': + description: Webhook received successfully + organization.sso_created: + post: + summary: SSO Connection Created + description: Triggered when a new SSO connection is created for an organization + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_94567862441607493 + type: organization.sso_created + object: Connection + environment_id: env_74418471961625391 + occurred_at: '2025-10-14T09:27:18.488720586Z' + organization_id: org_83544995172188677 + data: + id: conn_94567862424830277 + organization_id: org_83544995172188677 + connection_type: OIDC + provider: OKTA + display_name: SSO Connection Created + responses: + '200': + description: Webhook received successfully + organization.sso_enabled: + post: + summary: SSO Connection Enabled + description: Triggered when an SSO connection is enabled for an organization + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_94568078213382471 + type: organization.sso_enabled + object: Connection + environment_id: env_74418471961625391 + occurred_at: '2025-10-14T09:29:27.098914861Z' + organization_id: org_83544995172188677 + data: + id: conn_94567862424830277 + organization_id: org_83544995172188677 + connection_type: OIDC + provider: OKTA + enabled: true + status: COMPLETED + display_name: SSO Connection Enabled + responses: + '200': + description: Webhook received successfully + organization.sso_disabled: + post: + summary: SSO Connection Disabled + description: Triggered when an SSO connection is disabled for an organization + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_94557976165089560 + type: organization.sso_disabled + object: Connection + environment_id: env_74418471961625391 + occurred_at: '2025-10-14T07:49:05.809554456Z' + organization_id: org_83544995172188677 + data: + id: conn_83545002856153607 + organization_id: org_83544995172188677 + connection_type: OIDC + provider: OKTA + enabled: false + status: COMPLETED + display_name: SSO Connection Disabled + responses: + '200': + description: Webhook received successfully + organization.sso_deleted: + post: + summary: SSO Connection Deleted + description: Triggered when an SSO connection is deleted for an organization + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_94557997639926040 + type: organization.sso_deleted + object: Connection + environment_id: env_74418471961625391 + occurred_at: '2025-10-14T07:49:18.604546332Z' + organization_id: org_83544995172188677 + data: + id: conn_83545002856153607 + organization_id: org_83544995172188677 + connection_type: OIDC + provider: OKTA + display_name: SSO Connection Deleted + responses: + '200': + description: Webhook received successfully + role.created: + post: + summary: Role Created + description: Triggered when a new role is created + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_1234567890 + type: role.created + object: Role + occurred_at: '2024-01-15T10:30:00.123456789Z' + environment_id: env_1234567890 + data: + description: Viewer role with read-only access + display_name: Viewer + extends: member + id: role_1234567890 + name: viewer + display_name: Role Created + responses: + '200': + description: Webhook received successfully + role.updated: + post: + summary: Role Updated + description: Triggered when a role is updated + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_2345678901 + type: role.updated + object: Role + occurred_at: '2024-01-15T10:35:00.123456789Z' + environment_id: env_1234567890 + data: + description: Updated viewer role with limited permissions + display_name: Viewer + extends: member + id: role_1234567890 + name: viewer + display_name: Role Updated + responses: + '200': + description: Webhook received successfully + role.deleted: + post: + summary: Role Deleted + description: Triggered when a role is deleted + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_3456789012 + type: role.deleted + object: Role + occurred_at: '2024-01-15T10:40:00.123456789Z' + environment_id: env_1234567890 + data: + description: Updated viewer role with limited permissions + display_name: Viewer + extends: member + id: role_1234567890 + name: viewer + display_name: Role Deleted + responses: + '200': + description: Webhook received successfully + permission.created: + post: + summary: Permission Created + description: Triggered when a new permission is created + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_1234567890 + type: permission.created + object: Permission + occurred_at: '2024-01-15T10:30:00.123456789Z' + environment_id: env_1234567890 + data: + description: Permission to manage data + id: perm_1234567890 + name: data:manage + display_name: Permission Created + responses: + '200': + description: Webhook received successfully + permission.updated: + post: + summary: Permission Updated + description: Triggered when a permission is updated + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_2345678901 + type: permission.updated + object: Permission + occurred_at: '2024-01-15T10:35:00.123456789Z' + environment_id: env_1234567890 + data: + description: Updated permission to manage all data + id: perm_1234567890 + name: data:manage + display_name: Permission Updated + responses: + '200': + description: Webhook received successfully + permission.deleted: + post: + summary: Permission Deleted + description: Triggered when a permission is deleted + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScalekitEvent' + example: + spec_version: '1' + id: evt_3456789012 + type: permission.deleted + object: Permission + occurred_at: '2024-01-15T10:40:00.123456789Z' + environment_id: env_1234567890 + data: + description: Updated permission to manage all data + id: perm_1234567890 + name: data:manage + display_name: Permission Deleted + responses: + '200': + description: Webhook received successfully +components: + securitySchemes: + oauth2: + type: oauth2 + flows: + clientCredentials: + tokenUrl: https://$SCALEKIT_ENVIRONMENT_URL/oauth/token + scopes: + '': No scope required for client credentials flow + schemas: + connectionsConnectionProvider: + type: string + enum: + - OKTA + - GOOGLE + - MICROSOFT_AD + - AUTH0 + - ONELOGIN + - PING_IDENTITY + - JUMPCLOUD + - CUSTOM + - GITHUB + - GITLAB + - LINKEDIN + - SALESFORCE + - MICROSOFT + - IDP_SIMULATOR + - SCALEKIT + - ADFS + connectionsConnectionStatus: + type: string + enum: + - DRAFT + - IN_PROGRESS + - COMPLETED + connectionsConnectionType: + type: string + enum: + - OIDC + - SAML + - PASSWORD + - OAUTH + - PASSWORDLESS + - BASIC + - BEARER + - API_KEY + - WEBAUTHN + - OAUTH_M2M + - TRELLO_OAUTH1 + - GOOGLE_DWD + connectionsListConnection: + type: object + properties: + domains: + description: List of domains configured with this connection + type: array + items: + type: string + examples: + - - yourapp.com + - yourworkspace.com + enabled: + description: Whether the connection is currently active for organization users + type: boolean + examples: + - false + id: + description: Unique identifier of the connection + type: string + examples: + - conn_2123312131125533 + key_id: + description: Alternative identifier for this connection, typically used in frontend applications or URLs + type: string + examples: + - conn_2123312131125533 + organization_id: + description: Unique identifier of the organization that owns this connection + type: string + examples: + - org_2123312131125533 + organization_name: + description: Name of the organization of the connection + type: string + examples: + - Your Organization + provider: + description: Identity provider type (e.g., OKTA, Google, Azure AD) + $ref: '#/components/schemas/connectionsConnectionProvider' + examples: + - CUSTOM + provider_key: + description: Key ID of the identity provider service that handles authentication + type: string + examples: + - google + status: + description: Current configuration status of the connection + $ref: '#/components/schemas/connectionsConnectionStatus' + readOnly: true + examples: + - IN_PROGRESS + type: + description: Authentication protocol used by the connection + $ref: '#/components/schemas/connectionsConnectionType' + examples: + - OIDC + connectionsListConnectionsResponse: + type: object + properties: + connections: + description: List of connections matching the request criteria + type: array + items: + type: object + $ref: '#/components/schemas/connectionsListConnection' + UserServiceResendInviteBody: + type: object + usersInvite: + type: object + properties: + created_at: + description: Timestamp when the invite was originally created. + type: string + format: date-time + examples: + - '2025-07-10T08:00:00Z' + expires_at: + description: The time at which the invite expires. + type: string + format: date-time + examples: + - '2025-12-31T23:59:59Z' + inviter_email: + description: Identifier of the user or system that initiated the invite. + type: string + examples: + - admin@example.com + organization_id: + description: The organization to which the invite belongs. + type: string + examples: + - org_987654321 + resent_at: + description: Timestamp when the invite was last resent, if applicable. + type: string + format: date-time + examples: + - '2025-07-15T09:30:00Z' + resent_count: + description: Number of times the invite has been resent. + type: integer + format: int32 + examples: + - 2 + status: + description: Current status of the invite (e.g., pending, accepted, expired, revoked). + type: string + examples: + - pending_invite + user_id: + description: User ID to whom the invite is sent. May be empty if the user has not signed up yet. + type: string + examples: + - usr_123456 + usersResendInviteResponse: + type: object + properties: + invite: + description: Updated invitation object containing the resent invitation details, including new expiration time and incremented resend counter. + $ref: '#/components/schemas/usersInvite' + examples: + - expires_at: '2025-12-31T23:59:59Z' + organization_id: org_123 + resent_count: 2 + status: pending_invite + user_id: usr_456 + errdetailsDebugInfo: + description: Describes additional debugging info. + type: object + properties: + detail: + description: Additional debugging information provided by the server. + type: string + stack_entries: + description: The stack trace entries indicating where the error occurred. + type: array + items: + type: string + HelpInfoLink: + description: A documentation or reference link. + type: object + properties: + description: + description: Human-readable label for the link (e.g. "User verification flow"). + type: string + url: + description: Absolute URL to the documentation page (e.g. "https://docs.scalekit.com/..."). + type: string + errdetailsHelpInfo: + description: |- + HelpInfo provides documentation links attached to an error response. + When present in ErrorInfo, clients should surface these links to help + developers resolve the error. For example, a missing required field error + may include a link to the relevant guide. + type: object + properties: + links: + description: One or more links relevant to resolving the error. + type: array + items: + type: object + $ref: '#/components/schemas/HelpInfoLink' + errdetailsLocalizedMessageInfo: + type: object + properties: + locale: + type: string + message: + type: string + errdetailsRequestInfo: + description: |- + Contains metadata about the request that clients can attach when filing a bug + or providing other forms of feedback. + type: object + properties: + request_id: + description: |- + An opaque string that should only be interpreted by the service generating + it. For example, it can be used to identify requests in the service's logs. + type: string + serving_data: + description: |- + Any data that was used to serve this request. For example, an encrypted + stack trace that can be sent back to the service provider for debugging. + type: string + errdetailsResourceInfo: + description: Describes the resource that is being accessed. + type: object + properties: + description: + description: |- + Describes what error is encountered when accessing this resource. + For example, updating a cloud project may require the `writer` permission + on the developer console project. + type: string + owner: + type: string + required_permissions: + description: The required permissions needed to access the resource. + type: array + items: + type: string + resource_name: + type: string + user: + type: string + errdetailsToolErrorInfo: + type: object + properties: + execution_id: + type: string + tool_error_code: + type: string + tool_error_message: + type: string + ValidationErrorInfoFieldViolation: + description: A message type used to describe a single bad request field. + type: object + properties: + constraint: + type: string + description: + description: A description of why the request element is bad. + type: string + field: + type: string + errdetailsValidationErrorInfo: + description: |- + Describes violations in a client request. This error type focuses on the + syntactic aspects of the request. + type: object + properties: + field_violations: + description: Describes all violations in a client request. + type: array + items: + type: object + $ref: '#/components/schemas/ValidationErrorInfoFieldViolation' + errdetailsErrorInfo: + type: object + properties: + debug_info: + $ref: '#/components/schemas/errdetailsDebugInfo' + error_code: + type: string + help_info: + $ref: '#/components/schemas/errdetailsHelpInfo' + localized_message_info: + $ref: '#/components/schemas/errdetailsLocalizedMessageInfo' + request_info: + $ref: '#/components/schemas/errdetailsRequestInfo' + resource_info: + $ref: '#/components/schemas/errdetailsResourceInfo' + tool_error_info: + $ref: '#/components/schemas/errdetailsToolErrorInfo' + validation_error_info: + $ref: '#/components/schemas/errdetailsValidationErrorInfo' + commonsRole: + type: object + properties: + display_name: + description: Human-readable name for the role + type: string + examples: + - Dev Team + id: + description: Role ID + type: string + readOnly: true + examples: + - role_79643236410327240 + name: + description: Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + type: string + examples: + - team_dev + v1usersCreateMembership: + type: object + properties: + inviter_email: + description: Email address of the user who invited this member. Must be a valid email address. + type: string + examples: + - john.doe@example.com + metadata: + description: Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - department: engineering + location: nyc-office + roles: + description: Role to assign to the user within the organization + type: array + items: + type: object + $ref: '#/components/schemas/commonsRole' + examples: + - - name: admin + commonsMembershipStatus: + type: string + enum: + - ACTIVE + - INACTIVE + - PENDING_INVITE + - INVITE_EXPIRED + commonsOrganizationMembership: + type: object + properties: + accepted_at: + description: Timestamp when the user accepted the invitation. + type: string + format: date-time + created_at: + description: Timestamp when the invitation was created. + type: string + format: date-time + display_name: + description: Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + type: string + examples: + - Acme Corporation + expires_at: + description: Timestamp when the invitation expired. + type: string + format: date-time + inviter_email: + description: ID of the user who invited this user. + type: string + join_time: + description: Timestamp when the membership was created. Automatically set by the server. + type: string + format: date-time + membership_status: + $ref: '#/components/schemas/commonsMembershipStatus' + metadata: + description: Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - department: engineering + location: nyc-office + name: + description: Organization name. This field stores the formal organization name used for identification and display purposes. + type: string + examples: + - AcmeCorp + organization_id: + description: Unique identifier for the organization. Immutable and read-only. + type: string + examples: + - org_1234abcd5678efgh + permissions: + description: Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + type: array + items: + type: string + examples: + - - read_projects + - write_tasks + - manage_users + provisioning_method: + description: |- + How the user was provisioned. + Possible values: + - `jit_using_sso` (Just-in-time provisioning during SSO login) + - `allowed_email_domain` (User joined via allowed email domain matching) + - `org_creator` (User created the organization) + - `direct_provision` (User was directly provisioned via API or SCIM) + - `invitation` (User was invited and accepted an invitation) + type: string + roles: + type: array + items: + type: object + $ref: '#/components/schemas/commonsRole' + commonsIdentityProviderType: + type: string + enum: + - OKTA + - GOOGLE + - MICROSOFT_AD + - AUTH0 + - ONELOGIN + - PING_IDENTITY + - JUMPCLOUD + - CUSTOM + - GITHUB + - GITLAB + - LINKEDIN + - SALESFORCE + - MICROSOFT + - IDP_SIMULATOR + - SCALEKIT + - ADFS + commonsExternalIdentity: + type: object + properties: + connection_id: + description: Unique identifier for the external identity connection. Immutable and read-only. + type: string + readOnly: true + examples: + - conn_1234abcd5678efgh + connection_provider: + description: Type of the identity provider. + $ref: '#/components/schemas/commonsIdentityProviderType' + readOnly: true + examples: + - GOOGLE + connection_type: + description: Name of the external identity connection. + type: string + readOnly: true + examples: + - OAUTH + connection_user_id: + description: Unique identifier for the user in the external identity provider system. Immutable and read-only. + type: string + readOnly: true + examples: + - ext_user_12345 + created_time: + description: Timestamp when this external identity connection was first created. Immutable and read-only. + type: string + format: date-time + readOnly: true + is_social: + description: Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + type: boolean + readOnly: true + examples: + - true + last_login_time: + description: Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + type: string + format: date-time + readOnly: true + last_synced_time: + description: Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + type: string + format: date-time + readOnly: true + commonsUserProfile: + type: object + properties: + custom_attributes: + description: Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + type: object + additionalProperties: + type: string + examples: + - department: engineering + security_clearance: level2 + email_verified: + description: Indicates if the user's email address has been verified. Automatically updated by the system. + type: boolean + readOnly: true + examples: + - true + external_identities: + description: List of external identity connections associated with the user profile. + type: array + items: + type: object + $ref: '#/components/schemas/commonsExternalIdentity' + readOnly: true + family_name: + description: The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + type: string + examples: + - Doe + gender: + description: The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + type: string + examples: + - male + given_name: + description: The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + type: string + examples: + - John + groups: + description: The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + type: array + items: + type: string + examples: + - - admin + - developer + id: + description: Unique system-generated identifier for the user profile. Immutable and read-only. + type: string + readOnly: true + examples: + - usr_profile_1234abcd5678efgh + locale: + description: The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include `en-US`, `en-GB`, `fr-FR`, `de-DE`, and `es-ES`. + type: string + examples: + - en-US + metadata: + description: Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + type: object + additionalProperties: + type: string + examples: + - department: engineering + employee_type: full-time + idp_user_id: '12345' + name: + description: The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given_name and family_name fields. + type: string + examples: + - John Michael Doe + phone_number: + description: The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., `+1` for US numbers). This field is optional. + type: string + examples: + - '+14155552671' + phone_number_verified: + description: Indicates if the user's phone number has been verified. Automatically updated by the system. + type: boolean + readOnly: true + examples: + - true + picture: + description: The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + type: string + examples: + - https://example.com/avatar.jpg + preferred_username: + description: The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + type: string + examples: + - johndoe + usersUser: + type: object + properties: + create_time: + description: Timestamp when the user account was initially created. Automatically set by the server. + type: string + format: date-time + readOnly: true + email: + description: Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + type: string + examples: + - user@example.com + external_id: + description: Your application's unique identifier for this organization, used to link Scalekit with your system. + type: string + examples: + - ext_12345a67b89c + id: + description: Unique system-generated identifier for the user. Immutable once created. + type: string + examples: + - usr_1234abcd5678efgh + last_login_time: + description: Timestamp of the user's most recent successful authentication. Updated automatically. + type: string + format: date-time + readOnly: true + memberships: + description: List of organization memberships. Automatically populated based on group assignments. + type: array + items: + type: object + $ref: '#/components/schemas/commonsOrganizationMembership' + metadata: + description: Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - department: engineering + location: nyc-office + update_time: + description: Timestamp of the last modification to the user account. Automatically updated by the server. + type: string + format: date-time + readOnly: true + user_profile: + description: User's personal information including name, address, and other profile attributes. + $ref: '#/components/schemas/commonsUserProfile' + usersCreateMembershipResponse: + type: object + properties: + user: + $ref: '#/components/schemas/usersUser' + v1usersUpdateMembership: + type: object + properties: + metadata: + description: Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - department: engineering + location: nyc-office + roles: + description: Role to assign to the user within the organization + type: array + items: + type: object + $ref: '#/components/schemas/commonsRole' + examples: + - - name: admin + usersUpdateMembershipResponse: + type: object + properties: + user: + $ref: '#/components/schemas/usersUser' + commonsRegionCode: + type: string + enum: + - US + - EU + organizationsOrganizationSettingsFeature: + description: Controls the activation state of a specific organization feature + type: object + title: Organization Feature Toggle + required: + - name + - enabled + properties: + enabled: + description: Whether the feature is enabled (true) or disabled (false) for this organization + type: boolean + examples: + - true + name: + description: 'Feature identifier. Supported values include: "sso" (Single Sign-On), "directory_sync" (Directory Synchronization), "domain_verification" (Domain Verification), "session_policy" (Organization-level session policy override)' + type: string + examples: + - sso + organizationsOrganizationSettings: + description: Configuration options that control organization-level features and capabilities + type: object + title: Organization Settings + properties: + features: + description: List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization + type: array + items: + type: object + $ref: '#/components/schemas/organizationsOrganizationSettingsFeature' + examples: + - - enabled: true + name: sso + - enabled: false + name: directory_sync + examples: + - features: + - enabled: true + name: sso + - enabled: false + name: directory_sync + organizationsOrganization: + type: object + required: + - create_time + properties: + create_time: + description: Timestamp when the organization was created + type: string + format: date-time + title: Created Time + examples: + - '2025-02-15T06:23:44.560000Z' + display_name: + description: Name of the organization. Must be between 1 and 200 characters + type: string + title: Name of the org to be used in display + examples: + - Megasoft + external_id: + description: Your application's unique identifier for this organization, used to link Scalekit with your system. + type: string + title: External Id is useful to store a unique identifier for a given Org that. The unique Identifier can be the id of your tenant / org in your SaaSApp + examples: + - my_unique_id + id: + description: Unique scalekit-generated identifier that uniquely references an organization + type: string + title: Id + examples: + - org_59615193906282635 + logo_url: + description: HTTPS URL of the organization's logo image. Maximum 2048 characters. Must use the https scheme. + type: string + format: uri + maxLength: 2048 + pattern: ^https:// + examples: + - https://cdn.example.com/acme-logo.png + metadata: + description: Key value pairs extension attributes. + type: object + additionalProperties: + type: string + region_code: + description: Geographic region code for the organization. Currently limited to US. + title: Optional regioncode + $ref: '#/components/schemas/commonsRegionCode' + examples: + - US + settings: + title: Organization Settings + $ref: '#/components/schemas/organizationsOrganizationSettings' + slug: + description: DNS-safe slug for dynamic redirect URI resolution. Must be 1-63 chars, lowercase alphanumeric and hyphens, must start and end with an alphanumeric character. Unique per environment. + type: string + maxLength: 63 + minLength: 1 + pattern: ^[a-z0-9]([a-z0-9]|-[a-z0-9])*$ + examples: + - acme + update_time: + description: Timestamp when the organization was last updated + type: string + format: date-time + title: Updated time + examples: + - '2025-02-15T06:23:44.560000Z' + organizationsListOrganizationsResponse: + type: object + properties: + next_page_token: + description: Pagination token for the next page of results. Use this token to fetch the next page. + type: string + examples: + - + organizations: + description: List of organization objects + type: array + items: + type: object + $ref: '#/components/schemas/organizationsOrganization' + prev_page_token: + description: Pagination token for the previous page of results. Use this token to fetch the previous page. + type: string + examples: + - + total_size: + description: Total number of organizations in the environment. + type: integer + format: int64 + examples: + - 30 + v1organizationsCreateOrganization: + type: object + required: + - display_name + properties: + display_name: + description: Name of the organization. Must be between 1 and 200 characters. + type: string + examples: + - Megasoft Inc + external_id: + description: Your application's unique identifier for this organization, used to link Scalekit with your system. + type: string + examples: + - my_unique_id + logo_url: + description: HTTPS URL of the organization's logo image. Maximum 2048 characters. Must use the https scheme. + type: string + format: uri + maxLength: 2048 + pattern: ^https:// + examples: + - https://cdn.example.com/acme-logo.png + metadata: + type: object + additionalProperties: + type: string + slug: + description: DNS-safe slug for dynamic redirect URI resolution (e.g. acme for https://acme.example.com/callback). Lowercase alphanumeric and hyphens, 1-63 chars, must start and end with alphanumeric, unique per environment. + type: string + maxLength: 63 + minLength: 1 + pattern: ^[a-z0-9]([a-z0-9]|-[a-z0-9])*$ + examples: + - acme + organizationsCreateOrganizationResponse: + type: object + properties: + organization: + description: The newly created organization containing its ID, settings, and metadata + $ref: '#/components/schemas/organizationsOrganization' + organizationsGetOrganizationResponse: + type: object + properties: + organization: + description: The newly created organization + $ref: '#/components/schemas/organizationsOrganization' + v1organizationsUpdateOrganization: + description: For update messages ensure the indexes are same as the base model itself. + type: object + properties: + display_name: + description: Name of the organization to display in the UI. Must be between 1 and 200 characters + type: string + examples: + - Acme Corporation + external_id: + description: Your application's unique identifier for this organization, used to link Scalekit with your system + type: string + examples: + - tenant_12345 + logo_url: + description: HTTPS URL of the organization's logo image. Maximum 2048 characters. Must use the https scheme. + type: string + format: uri + maxLength: 2048 + pattern: ^https:// + examples: + - https://cdn.example.com/acme-logo.png + metadata: + description: Custom key-value pairs to store with the organization. Keys must be 3-25 characters, values must be 1-256 characters. Maximum 10 pairs allowed. + type: object + additionalProperties: + type: string + examples: + - industry: technology + slug: + description: DNS-safe slug for dynamic redirect URI resolution. Lowercase alphanumeric and hyphens, 1-63 chars, must start and end with alphanumeric, unique per environment. + type: string + maxLength: 63 + minLength: 1 + pattern: ^[a-z0-9]([a-z0-9]|-[a-z0-9])*$ + examples: + - acme + organizationsUpdateOrganizationResponse: + type: object + properties: + organization: + description: Updated organization details + $ref: '#/components/schemas/organizationsOrganization' + organizationsLink: + type: object + properties: + expire_time: + description: Expiry time of the link. The link is valid for 1 minute. + type: string + format: date-time + examples: + - '2024-02-06T14:48:00Z' + id: + description: Unique Identifier for the link + type: string + examples: + - lnk_123123123123123 + location: + description: Location of the link. This is the URL that can be used to access the Admin portal. The link is valid for 1 minute + type: string + examples: + - https://scalekit.com/portal/lnk_123123123123123 + organizationsGeneratePortalLinkResponse: + type: object + properties: + link: + description: 'Contains the generated admin portal link details. The link URL can be shared with organization administrators to set up: Single Sign-On (SSO) authentication and directory synchronization' + $ref: '#/components/schemas/organizationsLink' + rolesRolePermission: + type: object + title: RolePermissions represents a permission with role source information + properties: + create_time: + type: string + format: date-time + description: + type: string + id: + type: string + name: + type: string + role_name: + description: Name of the role from which this permission was sourced + type: string + examples: + - admin_role + update_time: + type: string + format: date-time + v1rolesRole: + type: object + properties: + default_creator: + description: Indicates if this role is the default creator role for new organizations. + type: boolean + examples: + - true + default_member: + description: Indicates if this role is the default member role for new users. + type: boolean + examples: + - true + dependent_roles_count: + description: Number of roles that extend from this role (dependent roles count). Read-only field. + type: integer + format: int32 + examples: + - 3 + description: + description: Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + type: string + examples: + - Can create, edit, and publish content but cannot delete or manage users + display_name: + description: Human-readable display name for the role. Used in user interfaces and reports. + type: string + examples: + - Content Editor + extends: + description: Name of the base role that this role extends. Enables hierarchical role inheritance. + type: string + examples: + - admin_role + id: + description: Unique system-generated identifier for the role. Immutable once created. + type: string + readOnly: true + examples: + - role_1234abcd5678efgh + is_org_role: + description: Indicates if this role is an organization role. + type: boolean + examples: + - true + name: + description: Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + type: string + examples: + - content_editor + permissions: + description: List of permissions with role source information. Only included when 'include' parameter is specified in the request. + type: array + items: + type: object + $ref: '#/components/schemas/rolesRolePermission' + examples: + - - description: Read Content + name: read:content + role_name: admin_role + - description: Write Content + name: write:content + role_name: editor_role + rolesListOrganizationRolesResponse: + type: object + properties: + roles: + description: List of roles objects + type: array + items: + type: object + $ref: '#/components/schemas/v1rolesRole' + v1rolesCreateOrganizationRole: + type: object + properties: + description: + description: Description of the organization's role + type: string + examples: + - Organization Viewer Role will be used only for viewing the objects + display_name: + description: Display name of the organization's role + type: string + examples: + - Organization Viewer Role + extends: + description: Base role name for hierarchical roles + type: string + examples: + - admin_role + name: + description: Unique name of the organization's role + type: string + examples: + - org_viewer_role + permissions: + description: List of permission names to assign to this role. Permissions must exist in the current environment. + type: array + items: + type: string + examples: + - - read:users + - write:documents + rolesCreateOrganizationRoleResponse: + type: object + properties: + role: + $ref: '#/components/schemas/v1rolesRole' + rolesGetOrganizationRoleResponse: + type: object + properties: + role: + $ref: '#/components/schemas/v1rolesRole' + v1rolesUpdateRole: + type: object + properties: + description: + description: Detailed description of the role's purpose, capabilities, and intended use cases. Maximum 2000 characters. + type: string + examples: + - Can create, edit, publish, and approve content. Cannot delete content or manage user accounts. + display_name: + description: Human-readable display name for the role. Used in user interfaces, reports, and user-facing communications. + type: string + examples: + - Senior Content Editor + extends: + description: Name of the base role that this role extends. Enables hierarchical role inheritance where this role inherits all permissions from the base role. + type: string + examples: + - content_editor + permissions: + description: List of permission names to assign to this role. When provided, this replaces all existing role-permission mappings. Permissions must exist in the current environment. Maximum 100 permissions per role. + type: array + items: + type: string + examples: + - - read:content + - write:content + - publish:content + - approve:content + rolesUpdateOrganizationRoleResponse: + type: object + properties: + role: + $ref: '#/components/schemas/v1rolesRole' + RolesServiceUpdateDefaultOrganizationRolesBody: + type: object + properties: + default_member_role: + description: Unique name of the default member role + type: string + examples: + - member + rolesUpdateDefaultOrganizationRolesResponse: + type: object + properties: + default_member: + description: Updated default member role + $ref: '#/components/schemas/v1rolesRole' + examples: + - description: Role for regular members + display_name: Member Role + id: role_0987654321 + name: member + clientsCustomClaim: + type: object + properties: + key: + description: The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose. + type: string + examples: + - environment + value: + description: The value of the custom claim. This value will be included in access tokens issued to the client. + type: string + examples: + - production + clientsClientSecretStatus: + description: |- + ClientSecretStatus indicates whether a client secret can be used for authentication. + ACTIVE secrets can be used for authentication while INACTIVE secrets cannot. + + - INACTIVE: The secret is inactive and cannot be used for authentication + type: string + enum: + - INACTIVE + clientsClientSecret: + description: A secure credential used for authenticating an API client. Each client can have multiple secrets for key rotation purposes. + type: object + title: Client Secret + properties: + create_time: + description: The timestamp when this secret was created. This field is automatically set by the server and cannot be modified. + type: string + format: date-time + examples: + - '2024-01-05T14:48:00Z' + created_by: + description: The identifier of the user or system that created this secret. This field helps track who created the secret for audit and compliance purposes. + type: string + examples: + - user_12345 + expire_time: + description: The timestamp when this secret will expire. After this time, the secret cannot be used for authentication regardless of its status. If not set, the secret does not expire. + type: string + format: date-time + examples: + - '2025-01-05T14:48:00Z' + id: + description: The unique identifier for this client secret. This ID is used to reference the secret in API requests for management operations like updating or deleting the secret. + type: string + examples: + - sec_1234abcd5678efgh + last_used_time: + description: The timestamp when this secret was last used for authentication. This field helps track secret usage for security monitoring and identifying unused secrets that may be candidates for rotation. + type: string + format: date-time + examples: + - '2024-02-15T10:30:00Z' + plain_secret: + description: The full plaintext secret value. This field is only populated when the secret is first created and is never stored by the server. It must be securely stored by the client application as it cannot be retrieved again. + type: string + examples: + - sec_1234567890abcdefghijklmnopqrstuvwxyz + secret_suffix: + description: A suffix that helps identify this secret. This is the last few characters of the full secret value but is not sufficient for authentication. Helps identify which secret is being used in logs and debugging. + type: string + examples: + - xyzw + status: + description: The current status of this secret. A secret must be ACTIVE to be used for authentication. INACTIVE secrets cannot be used for authentication but are retained for audit purposes. + $ref: '#/components/schemas/clientsClientSecretStatus' + examples: + - INACTIVE + update_time: + description: The timestamp when this secret was last updated. This field is automatically updated by the server when the secret's status changes or other properties are modified. + type: string + format: date-time + examples: + - '2024-01-10T09:12:00Z' + clientsM2MClient: + type: object + properties: + audience: + description: The intended recipients of access tokens issued to this client. Each audience value should be a URI that identifies an API or service. + type: array + items: + type: string + examples: + - - https://api.example.com + client_id: + description: The unique identifier for this API client. This ID is used to identify the client in API requests and logs. It is automatically generated when the client is created and cannot be modified. + type: string + examples: + - m2morg_1231234233424344 + create_time: + description: The timestamp when this API client was created. This field is automatically set by the server and cannot be modified. + type: string + format: date-time + examples: + - '2024-01-05T14:48:00Z' + custom_claims: + description: Additional claims included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. + type: array + items: + type: object + $ref: '#/components/schemas/clientsCustomClaim' + description: + description: A detailed description of the client's purpose and usage. This helps administrators understand what the client is used for. + type: string + examples: + - Service account for automated deployment processes + expiry: + description: Expiry time in seconds for the token generated by the client + type: string + format: int64 + examples: + - 3600 + is_cimd: + description: Indicates if the client was created via Client ID Metadata Document (CIMD). CIMD clients can update their own configuration according to the CIMD specification. + type: boolean + examples: + - false + is_dcr: + description: Indicates if the client was created via Dynamic Client Registration (DCR). Clients created through DCR may have different management and lifecycle policies compared to those created manually. + type: boolean + examples: + - false + metadata_uri: + description: The URI to the client's metadata, which is utilized to obtain the client's configuration details + type: string + examples: + - https://example.com/client-metadata.json + name: + description: The display name of the API client. This name helps identify the client in the dashboard and logs. + type: string + examples: + - GitHub Actions Deployment Service + organization_id: + description: The ID of the organization that owns this API client. This ID is used to associate the client with the correct organization and enforce organization-specific access controls. + type: string + examples: + - org_1231234233424344 + redirect_uris: + description: The redirect URI for this API client. This URI is used in the OAuth 2.0 authorization flow to redirect users after authentication. + type: array + items: + type: string + examples: + - - https://example.com/callback + resource_id: + description: The ID of the resource associated with this M2M client. This field is used to link the client to a specific resource in the system. + type: string + examples: + - app_1231234233424344 + scopes: + description: The OAuth 2.0 scopes granted to this client. These scopes determine what resources and actions the client can access. + type: array + items: + type: string + examples: + - - deploy:resources + - read:deployments + secrets: + description: List of client secrets associated with this client. Each secret can be used for authentication, but only the most recently created secret is typically active. Secrets are stored securely and their values are never returned after creation. + type: array + items: + type: object + $ref: '#/components/schemas/clientsClientSecret' + update_time: + description: The timestamp when this API client was last updated. This field is automatically updated by the server whenever the client's configuration changes. + type: string + format: date-time + examples: + - '2024-01-05T14:48:00Z' + clientsListOrganizationClientsResponse: + description: Response message containing a paginated list of API clients for the specified organization. + type: object + title: List Organization Clients Response + properties: + clients: + description: List of API client objects for the organization. Each client includes its configuration, metadata, and active secrets (without exposing actual secret values). + type: array + title: List of organization API clients + items: + type: object + $ref: '#/components/schemas/clientsM2MClient' + next_page_token: + description: Pagination token for the next page of results. Use this token to fetch the next page. + type: string + title: Pagination token for the next page of results + examples: + - + prev_page_token: + description: Pagination token for the previous page of results. Use this token to fetch the previous page. + type: string + title: Pagination token for the previous page of results + examples: + - + total_size: + description: Total number of API clients in the organization. + type: integer + format: int64 + title: Total number of clients in the organization + examples: + - 30 + clientsOrganizationClient: + type: object + properties: + audience: + description: The intended recipients of the access tokens issued to this client. Each audience value should be a URI that identifies the API or service that will validate the token. + type: array + items: + type: string + examples: + - - https://api.example.com/api/analytics + - https://deployment-api.acmecorp.com + custom_claims: + description: Additional claims to be included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. Keep claims minimal to avoid increasing token size. + type: array + items: + type: object + $ref: '#/components/schemas/clientsCustomClaim' + examples: + - - key: environment + value: production + - key: service + value: deployment + description: + description: A detailed explanation of the client's purpose and usage. This helps administrators understand what the client is used for and who manages it. + type: string + examples: + - Service account for GitHub Actions to deploy resources to production + expiry: + description: Expiry time in seconds for the token generated by the client + type: string + format: int64 + examples: + - 3600 + name: + description: A descriptive name for the API client that helps identify its purpose. This name is displayed in the dashboard and logs. Must be between 1 and 128 characters. + type: string + examples: + - GitHub Actions Deployment Service + scopes: + description: OAuth 2.0 scopes that define the permissions granted to this client. Each scope represents a specific permission or set of permissions. The client can only access resources that match its granted scopes. + type: array + items: + type: string + examples: + - - deploy:resources + - read:deployments + clientsCreateOrganizationClientResponse: + type: object + properties: + client: + description: Details of the created client + $ref: '#/components/schemas/clientsM2MClient' + plain_secret: + description: Client secret value (only returned once at creation) + type: string + examples: + - CdExsdErfccxDDssddfffgfeFHH1 + clientsGetOrganizationClientResponse: + type: object + properties: + client: + description: Details of the requested client + $ref: '#/components/schemas/clientsM2MClient' + clientsUpdateOrganizationClientResponse: + type: object + properties: + client: + description: Updated details of the client + $ref: '#/components/schemas/clientsM2MClient' + clientsCreateOrganizationClientSecretResponse: + type: object + properties: + plain_secret: + description: Client secret value (only returned once at creation) + type: string + examples: + - m2morg_client_secret_xyz123 + secret: + description: Details of the created client secret + $ref: '#/components/schemas/clientsClientSecret' + connectionsConfigurationType: + type: string + enum: + - DISCOVERY + - MANUAL + domainsVerificationMethod: + type: string + enum: + - ADMIN + - DNS + - NOT_APPLICABLE + domainsVerificationStatus: + type: string + enum: + - PENDING + - VERIFIED + - FAILED + - AUTO_VERIFIED + domainsDomain: + type: object + properties: + create_time: + description: Timestamp when the domain was first created. + type: string + format: date-time + examples: + - '2025-09-01T12:14:43.100000Z' + domain: + description: The business domain name that was configured for allowed email domain functionality (e.g., company.com, subdomain.company.com). + type: string + examples: + - customerdomain.com + domain_type: + example: ORGANIZATION_DOMAIN + environment_id: + description: The environment ID where this domain is configured. + type: string + examples: + - env_58345499215790610 + id: + description: Scalekit-generated unique identifier for this domain record. + type: string + examples: + - dom_88351643129225005 + organization_id: + description: The organization to which the domain belongs. + type: string + examples: + - org_81667076086825451 + update_time: + description: Timestamp when the domain was last updated. + type: string + format: date-time + examples: + - '2025-09-01T12:14:43.110455Z' + verification_method: + description: |- + Method that determines how domain ownership is verified. + - ADMIN: domain is marked verified without DNS validation, typically by an admin. + - DNS: domain must be verified by adding a TXT record to your DNS configuration. + - NOT_APPLICABLE: verification does not apply to this domain type. + $ref: '#/components/schemas/domainsVerificationMethod' + examples: + - ADMIN + verification_status: + description: |- + Verification status of the domain. + - PENDING: DNS TXT record has not been validated yet. + - VERIFIED: domain confirmed via DNS TXT record validation or admin approval. + - AUTO_VERIFIED: domain verified automatically without DNS changes. + - FAILED: DNS TXT record was not validated within the verification window. + $ref: '#/components/schemas/domainsVerificationStatus' + examples: + - AUTO_VERIFIED + connectionsGoogleDWDConfig: + type: object + properties: + scopes: + description: OAuth 2.0 scopes to request. + type: array + items: + type: string + service_account_json: + description: 'Google Cloud service account JSON key. Write-only: reads return a masked value.' + type: string + token_uri: + description: Google token endpoint. Defaults to https://oauth2.googleapis.com/token. + type: string + connectionsOptionalScopes: + type: object + properties: + field_name: + description: Name of the field in which scope should be sent in the authentication request. This is required by some identity providers that expect scopes to be sent in a custom field instead of the standard 'scope' parameter. + type: string + examples: + - optional_scope or bot_scope + scopes: + description: List of optional scopes that can be requested during authentication + type: array + items: + type: string + examples: + - - scope1 + - scope2 + connectionsOAuthConnectionConfig: + type: object + properties: + access_type: + description: Access Type + type: string + examples: + - offline + app_name: + description: Application name used by providers that require it as an authorize query parameter (e.g., Trello's app_name). + type: string + examples: + - My Trello App + authorize_uri: + description: Authorize URI + type: string + examples: + - https://youridp.com/service/oauth/authorize + client_id: + description: Client ID + type: string + examples: + - oauth_client_id + client_secret: + description: Client Secret + type: string + examples: + - oauth_client_secret + custom_scope_name: + description: Custom Scope Name + type: string + examples: + - user_scope + is_cimd: + description: Indicates whether this connection was registered using Client ID Metadata Document (CIMD) instead of Dynamic Client Registration. + type: boolean + readOnly: true + examples: + - true + optional_scopes: + description: Optional scopes configuration for identity providers that support or require additional scopes to be sent in a custom field during authentication requests. + $ref: '#/components/schemas/connectionsOptionalScopes' + pkce_enabled: + description: PKCE Enabled + type: boolean + examples: + - true + prompt: + description: Prompt for the user + type: string + examples: + - none + redirect_uri: + description: Redirect URI + type: string + examples: + - https://yourapp.com/service/oauth/redirect + scopes: + description: OIDC Scopes + type: array + items: + type: string + examples: + - - openid + - profile + sync_user_profile_on_login: + description: Indicates whether user profiles should be synchronized with the identity provider upon each log-in. + type: boolean + examples: + - true + tenant_id: + description: Microsoft Entra tenant ID. Required when using a single-tenant or multi-tenant app registered in Microsoft Entra. Leave empty to use the common endpoint. + type: string + examples: + - xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + token_access_type: + description: Token Access Type + type: string + examples: + - offline + token_uri: + description: Token URI + type: string + examples: + - https://youridp.com/service/oauth/token + use_platform_creds: + description: Use Scalekit credentials + type: boolean + examples: + - true + user_info_uri: + description: User Info URI + type: string + examples: + - https://youridp.com/service/oauth/userinfo + connectionsOIDCScope: + type: string + enum: + - openid + - profile + - email + - address + - phone + connectionsTokenAuthType: + type: string + enum: + - URL_PARAMS + - BASIC_AUTH + connectionsOIDCConnectionConfig: + type: object + properties: + authorize_uri: + description: Authorize URI + type: string + examples: + - https://youridp.com/service/oauth/authorize + backchannel_logout_redirect_uri: + description: backchannel logout redirect uri where idp sends logout_token + type: string + readOnly: true + examples: + - https://yourapp.com/sso/v1/oidc/conn_1234/backchannel-logout + client_id: + description: Client ID + type: string + examples: + - oauth_client_id + client_secret: + description: Client Secret + type: string + examples: + - oauth_client_secret + discovery_endpoint: + description: Discovery Endpoint + type: string + examples: + - https://youridp.com/service/oauth/.well-known/openid-configuration + idp_logout_required: + description: Enable IDP logout + type: boolean + examples: + - true + issuer: + description: Issuer URL + type: string + examples: + - https://youridp.com/service/oauth + jit_provisioning_with_sso_enabled: + description: Indicates if Just In Time user provisioning is enabled for the connection + type: boolean + examples: + - true + jwks_uri: + description: JWKS URI + type: string + examples: + - https://youridp.com/service/oauth/jwks + pkce_enabled: + description: PKCE Enabled + type: boolean + examples: + - true + post_logout_redirect_uri: + description: post logout redirect uri + type: string + readOnly: true + examples: + - https://yourapp.com/sso/v1/oidc/conn_1234/logout/callback + redirect_uri: + description: Redirect URI + type: string + examples: + - https://yourapp.com/sso/v1/oidc/conn_1234/callback + scopes: + description: OIDC Scopes + type: array + items: + $ref: '#/components/schemas/connectionsOIDCScope' + examples: + - - openid + - profile + sync_user_profile_on_login: + description: Indicates whether user profiles should be synchronized with the identity provider upon each log-in. + type: boolean + examples: + - true + token_auth_type: + description: Token Auth Type + $ref: '#/components/schemas/connectionsTokenAuthType' + examples: + - URL_PARAMS + token_uri: + description: Token URI + type: string + examples: + - https://youridp.com/service/oauth/token + user_info_uri: + description: User Info URI + type: string + examples: + - https://youridp.com/service/oauth/userinfo + connectionsCodeChallengeType: + type: string + enum: + - NUMERIC + - ALPHANUMERIC + connectionsPasswordlessType: + type: string + enum: + - LINK + - OTP + - LINK_OTP + connectionsPasswordLessConfig: + type: object + properties: + code_challenge_length: + description: Code Challenge Length + type: integer + format: int64 + examples: + - 6 + code_challenge_type: + description: Code Challenge Type + $ref: '#/components/schemas/connectionsCodeChallengeType' + examples: + - NUMERIC + enforce_same_browser_origin: + description: Enforce Same Browser Origin + type: boolean + examples: + - true + frequency: + description: Link Frequency + type: integer + format: int64 + examples: + - 1 + regenerate_passwordless_credentials_on_resend: + description: 'Regenerate the ' + type: boolean + examples: + - true + type: + description: Passwordless Type + $ref: '#/components/schemas/connectionsPasswordlessType' + examples: + - LINK + validity: + description: Link Validity in Seconds + type: integer + format: int64 + examples: + - 600 + connectionsIDPCertificate: + type: object + properties: + certificate: + description: IDP Certificate + type: string + create_time: + description: Certificate Creation Time + type: string + format: date-time + examples: + - '2021-09-01T00:00:00Z' + expiry_time: + description: Certificate Expiry Time + type: string + format: date-time + examples: + - '2021-09-01T00:00:00Z' + id: + description: Certificate ID + type: string + examples: + - cert_123123123123 + issuer: + description: Certificate Issuer + type: string + examples: + - https://youridp.com/service/saml + connectionsNameIdFormat: + type: string + enum: + - UNSPECIFIED + - EMAIL + - TRANSIENT + - PERSISTENT + connectionsRequestBinding: + type: string + enum: + - HTTP_POST + - HTTP_REDIRECT + connectionsSAMLSigningOptions: + type: string + title: enums all + enum: + - NO_SIGNING + - SAML_ONLY_RESPONSE_SIGNING + - SAML_ONLY_ASSERTION_SIGNING + - SAML_RESPONSE_ASSERTION_SIGNING + - SAML_RESPONSE_OR_ASSERTION_SIGNING + connectionsSAMLConnectionConfigResponse: + type: object + properties: + allow_idp_initiated_login: + description: Allow IDP Initiated Login + type: boolean + examples: + - true + assertion_encrypted: + description: Assertion Encrypted + type: boolean + examples: + - true + certificate_id: + description: Certificate ID + type: string + examples: + - cer_35585423166144613 + default_redirect_uri: + description: Default Redirect URI + type: string + examples: + - https://yourapp.com/service/saml/redirect + force_authn: + description: Force Authn + type: boolean + examples: + - true + idp_certificates: + description: IDP Certificates + type: array + items: + type: object + $ref: '#/components/schemas/connectionsIDPCertificate' + idp_entity_id: + description: IDP Entity ID + type: string + examples: + - https://youridp.com/service/saml + idp_metadata_url: + description: IDP Metadata URL + type: string + examples: + - https://youridp.com/service/saml/metadata + idp_name_id_format: + description: IDP Name ID Format + $ref: '#/components/schemas/connectionsNameIdFormat' + examples: + - EMAIL + idp_slo_request_binding: + description: IDP SLO Request Binding + $ref: '#/components/schemas/connectionsRequestBinding' + examples: + - HTTP_POST + idp_slo_required: + description: Enable IDP logout + type: boolean + examples: + - true + idp_slo_url: + description: IDP SLO URL + type: string + examples: + - https://youridp.com/service/saml/slo + idp_sso_request_binding: + description: IDP SSO Request Binding + $ref: '#/components/schemas/connectionsRequestBinding' + examples: + - HTTP_POST + idp_sso_url: + description: IDP SSO URL + type: string + examples: + - https://youridp.com/service/saml/sso + jit_provisioning_with_sso_enabled: + description: Indicates if Just In Time user provisioning is enabled for the connection + type: boolean + examples: + - true + saml_signing_option: + description: SAML Signing Option + $ref: '#/components/schemas/connectionsSAMLSigningOptions' + examples: + - SAML_ONLY_RESPONSE_SIGNING + sp_assertion_url: + description: SP Assertion URL + type: string + examples: + - https://youridp.com/service/saml/assertion + sp_entity_id: + description: SP Entity ID + type: string + examples: + - https://yourapp.com/service/saml + sp_metadata_url: + description: SP Metadata URL + type: string + examples: + - https://youridp.com/service/saml/metadata + sp_slo_url: + description: Service Provider SLO url + type: string + readOnly: true + examples: + - https://yourapp.com/sso/v1/saml/conn_1234/slo/callback + sync_user_profile_on_login: + description: Indicates whether user profiles should be synchronized with the identity provider upon each log-in. + type: boolean + examples: + - true + ui_button_title: + description: UI Button Title + type: string + examples: + - Login with SSO + want_request_signed: + description: Want Request Signed + type: boolean + examples: + - true + connectionsStaticAuthConfig: + type: object + properties: + static_config: + type: object + WebAuthConfigurationAttestation: + type: object + title: Attestation preferences for registration + properties: + conveyance_preference: + type: string + title: Conveyance preference + enterprise_approved_ids: + type: array + title: Enterprise-approved IDs (optional allowlist when enterprise attestation is used) + items: + type: string + WebAuthConfigurationAuthenticatorSelection: + type: object + properties: + authenticator_attachment: + type: string + user_verification: + type: string + title: User verification requirement + WebAuthConfigurationAuthenticators: + type: object + properties: + desired_authenticator_status: + description: provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate_status set to true. + type: array + items: + type: string + default: '[]' + undesired_authenticator_status: + description: provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate_status set to true. + type: array + items: + type: string + default: '[''ATTESTATION_KEY_COMPROMISE'', ''USER_VERIFICATION_BYPASS'', ''USER_KEY_REMOTE_COMPROMISE'', ''USER_KEY_PHYSICAL_COMPROMISE'', ''REVOKED'']' + validate_anchors: + description: when set to true enables the validation of the attestation statement against the trust anchor from the metadata statement. + type: boolean + validate_attestation_type: + description: when set to true enables the validation of the attestation statements type against the known types the authenticator can produce. + type: boolean + validate_entry: + description: requires that the provided metadata has an entry for the given authenticator to be considered valid. By default an AAGUID which has a zero value should fail validation if validate_entry_permit_zero_aaguid is not provided with the value of true. + type: boolean + validate_entry_permit_zero_aaguid: + description: is an option that permits a zero'd AAGUID from an attestation statement to automatically pass metadata validations. Generally helpful to use with validate_entry. + type: boolean + validate_status: + description: when set to true enables the validation of the attestation statements AAGUID against the desired and undesired lists + type: boolean + WebAuthConfigurationRp: + type: object + title: Rp contains relying party identifiers and origins + properties: + ids: + type: array + title: |- + Relying party IDs (derived from environment domain and verified custom domain) + At least one required; must be hostnames without scheme or path + items: + type: string + origins: + type: array + title: |- + Allowed origins corresponding to the RP IDs (https://) + At least one required; must be HTTPS origins + items: + type: string + WebAuthConfigurationTimeout: + type: object + properties: + login: + description: Login timeout duration + type: string + default: '"300s"' + login_uvd: + description: Login timeout duration when user verification is discouraged + type: string + default: '"300s"' + registration: + description: Registration timeout duration + type: string + default: '"300s"' + registration_uvd: + description: Registration timeout duration when user verification is discouraged + type: string + default: '"300s"' + connectionsWebAuthConfiguration: + type: object + title: WebAuthConfiguration defines WebAuthn (passkeys) configuration limited to RP and Attestation + properties: + attestation: + $ref: '#/components/schemas/WebAuthConfigurationAttestation' + authenticator_selection: + $ref: '#/components/schemas/WebAuthConfigurationAuthenticatorSelection' + authenticators: + $ref: '#/components/schemas/WebAuthConfigurationAuthenticators' + enable_auto_registration: + description: Enable auto registration for WebAuthn + type: boolean + enable_conditional_login: + description: Allow autofill of passkeys in login page + type: boolean + rp: + $ref: '#/components/schemas/WebAuthConfigurationRp' + show_passkey_button: + description: Show passkey button on login screen + type: boolean + timeout: + $ref: '#/components/schemas/WebAuthConfigurationTimeout' + connectionsConnection: + type: object + properties: + attribute_mapping: + description: 'Maps identity provider attributes to user profile fields. For example, {''email'': ''user.mail'', ''name'': ''user.displayName''}.' + type: object + additionalProperties: + type: string + configuration_type: + description: 'How the connection was configured: DISCOVERY (automatic configuration) or MANUAL (administrator configured)' + $ref: '#/components/schemas/connectionsConfigurationType' + examples: + - MANUAL + debug_enabled: + description: Enables testing mode that allows non-HTTPS endpoints. Should only be enabled in development environments, never in production. + type: boolean + examples: + - true + domains: + description: Domain associated with this connection, used for domain-based authentication flows. + type: array + items: + type: object + $ref: '#/components/schemas/domainsDomain' + examples: + - - name: example.com + enabled: + description: Controls whether users can sign in using this connection. When false, the connection exists but cannot be used for authentication. + type: boolean + examples: + - false + google_dwd_config: + description: Configuration details for Google Domain-Wide Delegation. Present only when type is GOOGLE_DWD. + $ref: '#/components/schemas/connectionsGoogleDWDConfig' + id: + description: Unique identifier for this connection. Used in API calls to reference this specific connection. + type: string + examples: + - conn_2123312131125533 + key_id: + description: Alternative identifier for this connection, typically used in frontend applications or URLs. + type: string + oauth_config: + description: Configuration details for OAuth connections. Present only when type is OAUTH. + $ref: '#/components/schemas/connectionsOAuthConnectionConfig' + oidc_config: + description: Configuration details for OpenID Connect (OIDC) connections. Present only when type is OIDC. + $ref: '#/components/schemas/connectionsOIDCConnectionConfig' + organization_id: + description: Identifier of the organization that owns this connection. Connections are typically scoped to a single organization. + type: string + examples: + - org_2123312131125533 + passwordless_config: + description: Configuration details for Magic Link authentication. Present only when type is MAGIC_LINK. + $ref: '#/components/schemas/connectionsPasswordLessConfig' + provider: + description: Identity provider service that handles authentication (such as OKTA, Google, Azure AD, or a custom provider) + $ref: '#/components/schemas/connectionsConnectionProvider' + examples: + - OKTA + provider_key: + description: Key ID of the identity provider service that handles authentication + type: string + examples: + - google + saml_config: + description: Configuration details for SAML connections. Present only when type is SAML. + $ref: '#/components/schemas/connectionsSAMLConnectionConfigResponse' + static_config: + description: Static configuration for custom connections. Present only when type is BASIC, BEARER, API_KEY, or custom. + $ref: '#/components/schemas/connectionsStaticAuthConfig' + status: + description: Current configuration status of the connection. Possible values include IN_PROGRESS, CONFIGURED, and ERROR. + $ref: '#/components/schemas/connectionsConnectionStatus' + readOnly: true + examples: + - IN_PROGRESS + test_connection_uri: + description: URI that can be used to test this connection. Visit this URL to verify the connection works correctly. + type: string + examples: + - https://auth.example.com/test-connection/conn_2123312131125533 + type: + description: Authentication protocol used by this connection. Can be OIDC (OpenID Connect), SAML, OAUTH, or MAGIC_LINK. + $ref: '#/components/schemas/connectionsConnectionType' + examples: + - OIDC + webauthn_config: + description: Configuration details for WebAuthn (passkeys). Present only when type is WEBAUTHN. + $ref: '#/components/schemas/connectionsWebAuthConfiguration' + connectionsGetConnectionResponse: + type: object + properties: + connection: + description: Complete connection details including provider configuration, protocol settings, status, and all metadata. Contains everything needed to understand the connection's current state. + $ref: '#/components/schemas/connectionsConnection' + connectionsToggleConnectionResponse: + type: object + properties: + enabled: + description: Current state of the connection after the operation. True means the connection is now enabled and can be used for authentication. + type: boolean + examples: + - true + error_message: + description: Error message if the operation fails + type: string + examples: + - placeholder + directoriesAttributeMapping: + type: object + properties: + key: + type: string + map_to: + type: string + directoriesAttributeMappings: + type: object + properties: + attributes: + type: array + items: + type: object + $ref: '#/components/schemas/directoriesAttributeMapping' + directoriesDirectoryProvider: + type: string + enum: + - OKTA + - GOOGLE + - MICROSOFT_AD + - AUTH0 + - ONELOGIN + - JUMPCLOUD + - PING_IDENTITY + directoriesDirectoryType: + type: string + enum: + - SCIM + - LDAP + - POLL + directoriesRoleAssignment: + type: object + properties: + group_id: + description: group ID for the role mapping + type: string + examples: + - dirgroup_121312434123 + role_name: + type: string + directoriesRoleAssignments: + type: object + properties: + assignments: + type: array + items: + type: object + $ref: '#/components/schemas/directoriesRoleAssignment' + directoriesSecretStatus: + type: string + enum: + - INACTIVE + directoriesSecret: + type: object + properties: + create_time: + description: Creation Time + type: string + format: date-time + examples: + - '2024-10-01T00:00:00Z' + directory_id: + description: Directory ID + type: string + examples: + - dir_12362474900684814 + expire_time: + description: Expiry Time + type: string + format: date-time + examples: + - '2025-10-01T00:00:00Z' + id: + type: string + last_used_time: + description: Last Used Time + type: string + format: date-time + examples: + - '2024-10-01T00:00:00Z' + secret_suffix: + description: Secret Suffix + type: string + examples: + - Nzg5 + status: + description: Secret Status + $ref: '#/components/schemas/directoriesSecretStatus' + examples: + - INACTIVE + directoriesStats: + type: object + properties: + group_updated_at: + description: Max time of Group Updated At for Directory + type: string + format: date-time + examples: + - '2024-10-01T00:00:00Z' + total_groups: + description: Total Groups in the Directory + type: integer + format: int32 + examples: + - 10 + total_users: + description: Total Users in the Directory + type: integer + format: int32 + examples: + - 10 + user_updated_at: + description: Max time of User Updated At for Directory + type: string + format: date-time + examples: + - '2024-10-01T00:00:00Z' + directoriesDirectory: + type: object + properties: + attribute_mappings: + description: Mappings between directory attributes and Scalekit user and group attributes + $ref: '#/components/schemas/directoriesAttributeMappings' + directory_endpoint: + description: The endpoint URL generated by Scalekit for synchronizing users and groups from the Directory Provider + type: string + examples: + - https://yourapp.scalekit.com/api/v1/directoies/dir_123212312/scim/v2 + directory_provider: + description: Identity provider connected to this directory + $ref: '#/components/schemas/directoriesDirectoryProvider' + examples: + - OKTA + directory_type: + description: Type of the directory, indicating the protocol or standard used for synchronization + $ref: '#/components/schemas/directoriesDirectoryType' + examples: + - SCIM + email: + description: Email Id associated with Directory whose access will be used for polling + type: string + examples: + - john.doe@scalekit.cloud + enabled: + description: Indicates whether the directory is currently enabled and actively synchronizing users and groups + type: boolean + examples: + - true + groups_tracked: + description: It indicates if all groups are tracked or select groups are tracked + type: string + examples: + - ALL + id: + description: Unique identifier of the directory + type: string + examples: + - dir_121312434123312 + last_synced_at: + description: Timestamp of the last successful synchronization of users and groups from the Directory Provider + type: string + format: date-time + examples: + - '2024-10-01T00:00:00Z' + name: + description: Name of the directory, typically representing the connected Directory provider + type: string + examples: + - Azure AD + organization_id: + description: Unique identifier of the organization to which the directory belongs + type: string + examples: + - org_121312434123312 + role_assignments: + description: Role assignments associated with the directory, defining group based role assignments + $ref: '#/components/schemas/directoriesRoleAssignments' + secrets: + description: List of secrets used for authenticating and synchronizing with the Directory Provider + type: array + items: + type: object + $ref: '#/components/schemas/directoriesSecret' + stats: + description: Statistics and metrics related to the directory, such as synchronization status and error counts + $ref: '#/components/schemas/directoriesStats' + status: + description: Directory Status + type: string + examples: + - IN_PROGRESS + total_groups: + description: Total number of groups in the directory + type: integer + format: int32 + examples: + - 10 + total_users: + description: Total number of users in the directory + type: integer + format: int32 + examples: + - 10 + directoriesListDirectoriesResponse: + type: object + properties: + directories: + description: List of directories associated with the organization + type: array + items: + type: object + $ref: '#/components/schemas/directoriesDirectory' + directoriesDirectoryGroup: + type: object + properties: + display_name: + description: Display Name + type: string + examples: + - Admins + group_detail: + description: Complete Group Details Payload + type: object + id: + description: Group ID + type: string + examples: + - dirgroup_121312434123312 + total_users: + description: Total Users in the Group + type: integer + format: int32 + examples: + - 10 + updated_at: + description: Updated At + type: string + format: date-time + examples: + - '2024-10-01T00:00:00Z' + directoriesListDirectoryGroupsResponse: + type: object + properties: + groups: + description: List of directory groups retrieved from the specified directory + type: array + items: + type: object + $ref: '#/components/schemas/directoriesDirectoryGroup' + next_page_token: + description: Token to retrieve the next page of results. Use this token in the 'page_token' field of the next request + type: string + prev_page_token: + description: Token to retrieve the previous page of results. Use this token in the 'page_token' field of the next request + type: string + total_size: + description: Total number of groups matching the request criteria, regardless of pagination + type: integer + format: int64 + directoriesDirectoryUser: + type: object + properties: + email: + description: Email + type: string + examples: + - johndoe + emails: + description: Emails + type: array + items: + type: string + family_name: + description: Last Name + type: string + examples: + - Doe + given_name: + description: First Name + type: string + examples: + - John + groups: + description: Groups + type: array + items: + type: object + $ref: '#/components/schemas/directoriesDirectoryGroup' + id: + description: User ID + type: string + examples: + - diruser_121312434123312 + preferred_username: + description: Preferred Username + type: string + examples: + - johndoe + updated_at: + description: Updated At + type: string + format: date-time + examples: + - '2024-10-01T00:00:00Z' + user_detail: + description: Complete User Details Payload + type: object + directoriesListDirectoryUsersResponse: + type: object + properties: + next_page_token: + description: Token for pagination. Use this token in the 'page_token' field of the next request to fetch the subsequent page of users + type: string + prev_page_token: + description: Token for pagination. Use this token in the 'page_token' field of the next request to fetch the prior page of users + type: string + total_size: + description: Total number of users available in the directory that match the request criteria + type: integer + format: int64 + users: + description: List of directory users retrieved from the specified directory + type: array + items: + type: object + $ref: '#/components/schemas/directoriesDirectoryUser' + directoriesGetDirectoryResponse: + type: object + properties: + directory: + description: Detailed information about the requested directory + $ref: '#/components/schemas/directoriesDirectory' + directoriesToggleDirectoryResponse: + type: object + properties: + enabled: + description: Specifies the directory's state after the toggle operation. A value of `true` indicates that the directory is enabled and actively synchronizing users and groups. A value of `false` means the directory is disabled, halting synchronization + type: boolean + examples: + - true + error_message: + description: Contains a human-readable error message if the toggle operation encountered an issue. If the operation was successful, this field will be empty + type: string + examples: + - The directory is already enabled + domainsListDomainResponse: + type: object + properties: + domains: + description: Array of domain objects containing all domain details including verification status and configuration. + type: array + items: + type: object + $ref: '#/components/schemas/domainsDomain' + page_number: + description: Current page number in the pagination sequence. + type: integer + format: int32 + examples: + - 1 + page_size: + description: Number of domains returned in this page. + type: integer + format: int32 + examples: + - 1 + domainsDomainType: + type: string + enum: + - ALLOWED_EMAIL_DOMAIN + - ORGANIZATION_DOMAIN + x-enum-varnames: + - ORGANIZATION_DOMAIN + - ALLOWED_EMAIL_DOMAIN + v1domainsCreateDomain: + type: object + properties: + domain: + description: The domain name to be configured. Must be a valid business domain you control. Public and disposable domains (gmail.com, outlook.com, etc.) are automatically blocked for security. + type: string + examples: + - customerdomain.com + domain_type: + description: | + The domain type. + - ALLOWED_EMAIL_DOMAIN: trusted domain used to suggest the organization in the organization switcher during sign-in/sign-up. + - ORGANIZATION_DOMAIN: SSO discovery domain used to route users to the correct SSO provider and enforce SSO. + $ref: '#/components/schemas/domainsDomainType' + examples: + - ORGANIZATION_DOMAIN + domainsCreateDomainResponse: + type: object + properties: + domain: + description: The newly created domain object with all configuration details and system-generated identifiers. + $ref: '#/components/schemas/domainsDomain' + domainsGetDomainResponse: + type: object + properties: + domain: + description: The requested domain object with complete details including domain type, timestamps and configuration. + $ref: '#/components/schemas/domainsDomain' + commonsTimeUnit: + type: string + enum: + - MINUTES + - HOURS + - DAYS + organizationsSessionPolicyType: + type: string + enum: + - APPLICATION + - CUSTOM + organizationsOrganizationSessionPolicySettings: + type: object + properties: + absolute_session_timeout: + description: The absolute session timeout value. The unit is specified by absolute_session_timeout_unit. Omitted when policy_source is 'environment'. + type: integer + format: int32 + examples: + - 360 + absolute_session_timeout_unit: + description: 'Unit for absolute_session_timeout. Accepted values: ''minutes'', ''hours'', ''days''. Responses always return ''minutes''.' + $ref: '#/components/schemas/commonsTimeUnit' + examples: + - minutes + idle_session_timeout: + description: The idle session timeout value. The unit is specified by idle_session_timeout_unit. Omitted when idle_session_timeout_enabled is false or policy_source is 'environment'. + type: integer + format: int32 + examples: + - 84 + idle_session_timeout_enabled: + description: Whether idle session timeout is enabled for this organization. Omitted when policy_source is 'environment'. + type: boolean + examples: + - true + idle_session_timeout_unit: + description: 'Unit for idle_session_timeout. Accepted values: ''minutes'', ''hours'', ''days''. Responses always return ''minutes''.' + $ref: '#/components/schemas/commonsTimeUnit' + examples: + - minutes + policy_source: + description: Policy source. 'APPLICATION' means the organization inherits the application-level session policy. 'CUSTOM' means organization-specific timeout values are active. + $ref: '#/components/schemas/organizationsSessionPolicyType' + examples: + - CUSTOM + organizationsGetOrganizationSessionPolicyResponse: + type: object + properties: + policy: + description: The session policy for the organization. + $ref: '#/components/schemas/organizationsOrganizationSessionPolicySettings' + OrganizationServiceUpdateOrganizationSessionPolicyBody: + type: object + properties: + absolute_session_timeout: + description: The absolute session timeout value. The unit is specified by absolute_session_timeout_unit. Omit when policy_source is APPLICATION. + type: integer + format: int32 + examples: + - 360 + absolute_session_timeout_unit: + description: 'Unit for absolute_session_timeout. Accepted values: ''MINUTES'', ''HOURS'', ''DAYS''. Defaults to MINUTES.' + $ref: '#/components/schemas/commonsTimeUnit' + examples: + - MINUTES + idle_session_timeout: + description: The idle session timeout value. The unit is specified by idle_session_timeout_unit. Omit when idle_session_timeout_enabled is false. + type: integer + format: int32 + examples: + - 84 + idle_session_timeout_enabled: + description: Whether idle session timeout is enabled. Omit when policy_source is APPLICATION. + type: boolean + examples: + - true + idle_session_timeout_unit: + description: 'Unit for idle_session_timeout. Accepted values: ''MINUTES'', ''HOURS'', ''DAYS''. Defaults to MINUTES.' + $ref: '#/components/schemas/commonsTimeUnit' + examples: + - MINUTES + policy_source: + description: Policy source. Send 'APPLICATION' to revert to application defaults. Send 'CUSTOM' with timeout values to activate a custom policy. + $ref: '#/components/schemas/organizationsSessionPolicyType' + examples: + - CUSTOM + organizationsUpdateOrganizationSessionPolicyResponse: + type: object + properties: + policy: + description: The updated session policy for the organization. + $ref: '#/components/schemas/organizationsOrganizationSessionPolicySettings' + organizationsOrganizationUserManagementSettings: + type: object + properties: + max_allowed_users: + description: Maximum number of users allowed in the organization. When nil (not set), there feature is not enabled. When explicitly set to zero, it also means no limit. When set to a positive integer, it enforces the maximum user limit. + type: integer + format: int32 + examples: + - 100 + OrganizationServiceUpsertUserManagementSettingsBody: + type: object + properties: + settings: + description: The new values for the setting fields to patch. + $ref: '#/components/schemas/organizationsOrganizationUserManagementSettings' + organizationsUpsertUserManagementSettingsResponse: + type: object + properties: + settings: + description: The updated setting. + $ref: '#/components/schemas/organizationsOrganizationUserManagementSettings' + usersListOrganizationUsersResponse: + type: object + properties: + next_page_token: + description: Opaque token for retrieving the next page of results. Empty if there are no more pages. + type: string + examples: + - eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0= + prev_page_token: + description: Opaque token for retrieving the previous page of results. Empty for the first page. + type: string + examples: + - eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9 + total_size: + description: Total number of users matching the request criteria, regardless of pagination. + type: integer + format: int64 + examples: + - 1042 + users: + description: List of user objects for the current page. May contain fewer entries than requested page_size. + type: array + items: + type: object + $ref: '#/components/schemas/usersUser' + usersCreateUserProfile: + type: object + properties: + custom_attributes: + description: Custom attributes for extended user profile data. Keys (3-25 chars), values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - department: engineering + security_clearance: level2 + family_name: + description: User's family name. Maximum 255 characters. + type: string + examples: + - Doe + gender: + description: User's gender identity. + type: string + examples: + - male + given_name: + description: User's given name. Maximum 255 characters. + type: string + examples: + - John + groups: + description: List of group names the user belongs to. Each group name must be 1-250 characters + type: array + items: + type: string + examples: + - - engineering + - managers + locale: + description: User's localization preference in BCP-47 format. Defaults to organization settings. + type: string + examples: + - en-US + metadata: + description: System-managed key-value pairs for internal tracking. Keys (3-25 chars), values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - account_status: active + signup_source: mobile_app + name: + description: Full name in display format. Typically combines first_name and last_name. + type: string + examples: + - John Michael Doe + phone_number: + description: Phone number in E.164 international format. Required for SMS-based authentication. + type: string + examples: + - '+14155552671' + picture: + description: URL to the user's profile picture or avatar. + type: string + examples: + - https://example.com/avatar.jpg + preferred_username: + description: User's preferred username for display purposes. + type: string + examples: + - John Michael Doe + usersCreateUser: + type: object + properties: + email: + description: Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + type: string + examples: + - user@example.com + external_id: + description: Your application's unique identifier for this organization, used to link Scalekit with your system. + type: string + examples: + - ext_12345a67b89c + membership: + description: List of organization memberships. Automatically populated based on group assignments. + $ref: '#/components/schemas/v1usersCreateMembership' + metadata: + description: Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - department: engineering + location: nyc-office + user_profile: + description: User's personal information including name, address, and other profile attributes. + $ref: '#/components/schemas/usersCreateUserProfile' + usersCreateUserAndMembershipResponse: + type: object + properties: + user: + $ref: '#/components/schemas/usersUser' + usersPermission: + type: object + properties: + description: + description: Description of what the permission allows + type: string + examples: + - Allows creating new user accounts + id: + description: Unique identifier for the permission + type: string + readOnly: true + examples: + - perm_1234abcd5678efgh + name: + description: Unique name identifier for the permission + type: string + examples: + - users:create + usersListUserPermissionsResponse: + type: object + properties: + permissions: + description: List of permissions the user has access to + type: array + items: + type: object + $ref: '#/components/schemas/usersPermission' + usersListUserRolesResponse: + type: object + properties: + roles: + description: List of roles assigned to the user + type: array + items: + type: object + $ref: '#/components/schemas/commonsRole' + usersSearchOrganizationUsersResponse: + type: object + properties: + next_page_token: + description: Token for retrieving the next page of results. Empty if there are no more pages. + type: string + examples: + - eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0= + prev_page_token: + description: Token for retrieving the previous page of results. Empty if this is the first page. + type: string + examples: + - eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9 + total_size: + description: Total number of users matching the request criteria, regardless of pagination. + type: integer + format: int64 + examples: + - 1042 + users: + description: List of matching users. + type: array + items: + type: object + $ref: '#/components/schemas/usersUser' + passwordlessResendPasswordlessRequest: + type: object + properties: + auth_request_id: + description: The authentication request identifier from the original send passwordless email request. Use this to resend the Verification Code (OTP) or Magic Link to the same email address. + type: string + examples: + - h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ + authpasswordlessPasswordlessType: + type: string + enum: + - OTP + - LINK + - LINK_OTP + passwordlessSendPasswordlessResponse: + type: object + properties: + auth_request_id: + description: Unique identifier for this passwordless authentication request. Use this ID to resend emails. + type: string + readOnly: true + examples: + - h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ + expires_at: + description: Unix timestamp (seconds since epoch) when the passwordless authentication will expire. After this time, the OTP or magic link will no longer be valid. + type: string + format: int64 + readOnly: true + examples: + - 1748696575 + expires_in: + description: Number of seconds from now until the passwordless authentication expires. This is a convenience field calculated from the expires_at timestamp. + type: integer + format: int64 + readOnly: true + examples: + - 300 + passwordless_type: + description: Type of passwordless authentication that was sent via email. OTP sends a numeric code, LINK sends a clickable magic link, and LINK_OTP provides both options for user convenience. + $ref: '#/components/schemas/authpasswordlessPasswordlessType' + examples: + - OTP + passwordlessTemplateType: + type: string + enum: + - SIGNIN + - SIGNUP + passwordlessSendPasswordlessRequest: + type: object + properties: + email: + description: Email address where the passwordless authentication credentials will be sent. Must be a valid email format. + type: string + examples: + - john.doe@example.com + expires_in: + description: Time in seconds until the passwordless authentication expires. If not specified, defaults to 300 seconds (5 minutes) + type: integer + format: int64 + examples: + - 300 + magiclink_auth_uri: + description: Your application's callback URL where users will be redirected after clicking the magic link in their email. The link token will be appended as a query parameter as link_token + type: string + examples: + - https://yourapp.com/auth/passwordless/callback + state: + description: Custom state parameter that will be returned unchanged in the verification response. Use this to maintain application state between the authentication request and callback, such as the intended destination after login + type: string + examples: + - d62ivasry29lso + template: + description: Specifies the authentication intent for the passwordless request. Use SIGNIN for existing users or SIGNUP for new user registration. This affects the email template and user experience flow. + $ref: '#/components/schemas/passwordlessTemplateType' + examples: + - SIGNIN + template_variables: + description: |- + A set of key-value pairs to personalize the email template. + + * You may include up to 30 key-value pairs. + * The following variable names are reserved by the system and cannot be supplied: `otp`, `expiry_time_relative`, `link`, `expire_time`, `expiry_time`. + * Every variable referenced in your email template must be included as a key-value pair. + + Use these variables to insert custom information, such as a team name, URL or the user's employee ID. All variables are interpolated before the email is sent, regardless of the email provider. + type: object + additionalProperties: + type: string + examples: + - custom_variable_key: custom_variable_value + passwordlessVerifyPasswordLessRequest: + type: object + properties: + auth_request_id: + description: The authentication request identifier returned from the send passwordless email endpoint. Required when verifying OTP codes to link the verification with the original request. + type: string + examples: + - h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ + code: + description: The Verification Code (OTP) received via email. This is typically a 6-digit numeric code that users enter manually to verify their identity. + type: string + examples: + - '123456' + link_token: + description: The unique token from the magic link URL received via email. Extract this token when users click the magic link and are redirected to your application to later verify the user. + type: string + examples: + - afe9d61c-d80d-4020-a8ee-61765ab71cb3 + passwordlessVerifyPasswordLessResponse: + type: object + properties: + email: + description: Email address of the successfully authenticated user. This confirms which email account was verified through the passwordless flow. + type: string + readOnly: true + examples: + - john.doe@example.com + passwordless_type: + description: The type of passwordless authentication that was successfully verified, confirming which method the user completed. + $ref: '#/components/schemas/authpasswordlessPasswordlessType' + examples: + - OTP + state: + description: The custom state parameter that was provided in the original authentication request, returned unchanged. Use this to restore your application's context after authentication. + type: string + readOnly: true + examples: + - kdt7yiag28t341fr1 + template: + description: Specifies which email template to choose. For User Signin choose SIGNIN and for User Signup use SIGNUP + $ref: '#/components/schemas/passwordlessTemplateType' + examples: + - SIGNIN + rolesPermission: + type: object + title: Permission Entity + properties: + create_time: + type: string + format: date-time + description: + type: string + id: + type: string + is_scalekit_permission: + description: Indicates whether this permission is predefined by Scalekit + type: boolean + examples: + - true + name: + type: string + update_time: + type: string + format: date-time + rolesListPermissionsResponse: + type: object + properties: + next_page_token: + description: Token to retrieve next page of results + type: string + examples: + - token_def456 + permissions: + type: array + items: + type: object + $ref: '#/components/schemas/rolesPermission' + prev_page_token: + description: Token to retrieve previous page of results + type: string + examples: + - token_def456 + total_size: + description: Total number of permissions available + type: integer + format: int64 + examples: + - 150 + v1rolesCreatePermission: + type: object + properties: + description: + description: Description of the permission + type: string + examples: + - Allows user to read documents from the system + name: + description: Unique name/ID of the permission + type: string + examples: + - read:documents + rolesCreatePermissionResponse: + type: object + properties: + permission: + $ref: '#/components/schemas/rolesPermission' + rolesGetPermissionResponse: + type: object + properties: + permission: + $ref: '#/components/schemas/rolesPermission' + rolesUpdatePermissionResponse: + type: object + properties: + permission: + $ref: '#/components/schemas/rolesPermission' + rolesListRolesResponse: + type: object + properties: + roles: + description: List of all roles in the environment with their metadata and optionally their permissions. + type: array + items: + type: object + $ref: '#/components/schemas/v1rolesRole' + examples: + - - display_name: Administrator + id: role_1234abcd5678efgh + name: admin + - display_name: Viewer + id: role_9876zyxw5432vuts + name: viewer + v1rolesCreateRole: + type: object + properties: + description: + description: Detailed description of the role's purpose, capabilities, and intended use cases. Maximum 2000 characters. + type: string + examples: + - Can create, edit, and publish content but cannot delete content or manage user accounts + display_name: + description: Human-readable display name for the role. Used in user interfaces, reports, and user-facing communications. + type: string + examples: + - Content Editor + extends: + description: Name of the base role that this role extends. Enables hierarchical role inheritance where this role inherits all permissions from the base role. + type: string + examples: + - viewer + name: + description: Unique name identifier for the role. Must be alphanumeric with underscores, 1-64 characters. This name is used in API calls and cannot be changed after creation. + type: string + examples: + - content_editor + permissions: + description: List of permission names to assign to this role. Permissions must exist in the current environment. Maximum 100 permissions per role. + type: array + items: + type: string + examples: + - - read:content + - write:content + - publish:content + rolesCreateRoleResponse: + type: object + properties: + role: + description: The created role object with system-generated ID and all configuration details. + $ref: '#/components/schemas/v1rolesRole' + examples: + - description: Can edit content + display_name: Content Editor + id: role_1234abcd5678efgh + name: content_editor + rolesUpdateDefaultRole: + type: object + properties: + id: + type: string + name: + description: Unique name of the role + type: string + examples: + - creator + rolesUpdateDefaultRolesRequest: + type: object + properties: + default_creator: + description: Default creator role (deprecated - use default_creator_role field instead) + $ref: '#/components/schemas/rolesUpdateDefaultRole' + examples: + - description: Role for creating resources + display_name: Creator Role + id: role_1234567890 + name: creator + default_creator_role: + description: Name of the role to set as the default creator role. This role will be automatically assigned to users who create new resources in the environment. Must be a valid role name that exists in the environment. + type: string + examples: + - creator + default_member: + description: Default member role (deprecated - use default_member_role field instead) + $ref: '#/components/schemas/rolesUpdateDefaultRole' + examples: + - description: Role for regular members + display_name: Member Role + id: role_0987654321 + name: member + default_member_role: + description: Name of the role to set as the default member role. This role will be automatically assigned to new users when they join the environment. Must be a valid role name that exists in the environment. + type: string + examples: + - member + rolesUpdateDefaultRolesResponse: + type: object + properties: + default_creator: + description: The role that is now set as the default creator role for the environment. Contains complete role information including permissions and metadata. + $ref: '#/components/schemas/v1rolesRole' + examples: + - description: Role for creating resources + display_name: Creator Role + id: role_1234567890 + name: creator + default_member: + description: The role that is now set as the default member role for the environment. Contains complete role information including permissions and metadata. + $ref: '#/components/schemas/v1rolesRole' + examples: + - description: Role for regular members + display_name: Member Role + id: role_0987654321 + name: member + rolesGetRoleResponse: + type: object + properties: + role: + description: The complete role object with all metadata, permissions, and inheritance details. + $ref: '#/components/schemas/v1rolesRole' + examples: + - dependent_roles_count: 2 + display_name: Content Editor + id: role_1234abcd5678efgh + name: content_editor + permissions: + - name: read:content + rolesUpdateRoleResponse: + type: object + properties: + role: + description: The updated role object with all current configuration details. + $ref: '#/components/schemas/v1rolesRole' + examples: + - description: Can edit and approve content + display_name: Senior Editor + id: role_1234abcd5678efgh + name: content_editor + rolesListDependentRolesResponse: + type: object + properties: + roles: + description: List of dependent roles + type: array + items: + type: object + $ref: '#/components/schemas/v1rolesRole' + rolesListRolePermissionsResponse: + type: object + properties: + permissions: + description: List of permissions directly assigned to the role + type: array + items: + type: object + $ref: '#/components/schemas/rolesPermission' + RolesServiceAddPermissionsToRoleBody: + type: object + properties: + permission_names: + description: List of permission names to add to the role + type: array + items: + type: string + rolesAddPermissionsToRoleResponse: + type: object + properties: + permissions: + description: List of all permissions belonging to the role after addition + type: array + items: + type: object + $ref: '#/components/schemas/rolesPermission' + rolesListEffectiveRolePermissionsResponse: + type: object + properties: + permissions: + description: List of all effective permissions including those inherited from base roles + type: array + items: + type: object + $ref: '#/components/schemas/rolesPermission' + rolesGetRoleUsersCountResponse: + type: object + properties: + count: + description: Number of users associated with the role + type: string + format: int64 + examples: + - 10 + sessionsAuthenticatedClients: + description: AuthenticatedClients represents an authenticated client in a session along with its organization context. + type: object + properties: + client_id: + description: Unique identifier of the authenticated client application. + type: string + examples: + - skc_1234567890 + organization_id: + description: Active or last active Organization ID associated with the authenticated client. + type: string + examples: + - org_1234567890 + v1sessionsLocation: + type: object + properties: + city: + description: City name where the session originated based on IP geolocation. Approximate location derived from IP address. + type: string + examples: + - San Francisco + latitude: + description: 'Latitude coordinate of the estimated location. Decimal format (e.g., ''37.7749''). Note: Represents IP geolocation center and may not be precise.' + type: string + examples: + - '37.7749' + longitude: + description: 'Longitude coordinate of the estimated location. Decimal format (e.g., ''-122.4194''). Note: Represents IP geolocation center and may not be precise.' + type: string + examples: + - '-122.4194' + region: + description: Geographic region name derived from IP geolocation. Represents the country-level location (e.g., 'United States', 'France'). + type: string + examples: + - United States + region_subdivision: + description: Regional subdivision code or name (e.g., state abbreviation for US, province for Canada). Two-letter ISO format when applicable. + type: string + examples: + - CA + sessionsDeviceDetails: + type: object + properties: + browser: + description: 'Browser name and family extracted from the user agent. Examples: Chrome, Safari, Firefox, Edge, Mobile Safari.' + type: string + examples: + - Chrome + browser_version: + description: Version of the browser application. Represents the specific release version of the browser being used. + type: string + examples: + - 120.0.0.0 + device_type: + description: 'Categorized device type classification. Possible values: ''desktop'' (traditional computers), ''mobile'' (smartphones and small tablets), ''tablet'' (large tablets), ''other''. Useful for displaying session information by device category.' + type: string + examples: + - desktop + ip: + description: IP address of the device that initiated the session. This is the public-facing IP address used to connect to the application. Useful for security audits and geographic distribution analysis. + type: string + examples: + - 192.0.2.1 + location: + description: 'Geographic location information derived from IP address geolocation. Includes country, region, city, and coordinates. Note: Based on IP location data and may not represent the user''s exact physical location.' + $ref: '#/components/schemas/v1sessionsLocation' + os: + description: 'Operating system name extracted from the user agent and device headers. Examples: macOS, Windows, Linux, iOS, Android.' + type: string + examples: + - macOS + os_version: + description: Version of the operating system. Represents the specific OS release the device is running. + type: string + examples: + - '14.2' + user_agent: + description: Complete HTTP User-Agent header string from the client request. Contains browser type, version, and operating system information. Used for detailed device fingerprinting and user agent analysis. + type: string + examples: + - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 + sessionsSessionDetails: + type: object + properties: + absolute_expires_at: + description: Hard expiration timestamp for the session regardless of user activity. The session will be forcibly terminated at this time. This represents the maximum session lifetime from creation. + type: string + format: date-time + examples: + - '2025-01-22T10:30:00Z' + authenticated_clients: + description: 'Details of the authenticated clients for this session: client ID and organization context.' + type: array + items: + type: object + $ref: '#/components/schemas/sessionsAuthenticatedClients' + authenticated_organizations: + description: List of organization IDs that have been authenticated for this user within the current session. Contains all organizations where the user has successfully completed SSO or authentication. + type: array + items: + type: string + examples: + - - org_123 + - org_456 + created_at: + description: Timestamp indicating when the session was created. This is set once at session creation and remains constant throughout the session lifetime. + type: string + format: date-time + examples: + - '2025-01-15T10:30:00Z' + device: + description: Complete device metadata associated with this session including browser, operating system, device type, and geographic location based on IP address. + $ref: '#/components/schemas/sessionsDeviceDetails' + expired_at: + description: Timestamp when the session was terminated. Null if the session is still active. Set when the session expires due to reaching idle_expires_at or absolute_expires_at timeout, or when administratively revoked. Not set for user-initiated logout (see logout_at instead). + type: string + format: date-time + examples: + - '2025-01-15T12:00:00Z' + idle_expires_at: + description: Projected expiration timestamp if the session remains idle without user activity. This timestamp is recalculated with each user activity. Session will be automatically terminated at this time if no activity occurs. + type: string + format: date-time + examples: + - '2025-01-15T11:30:00Z' + last_active_at: + description: Timestamp of the most recent user activity detected in this session. Updated on each API request or user interaction. Used to determine if a session has exceeded the idle timeout threshold. + type: string + format: date-time + examples: + - '2025-01-15T10:55:30Z' + logout_at: + description: Timestamp when the user explicitly logged out from the session. Null if the user has not logged out. When set, indicates the session ended due to explicit user logout rather than timeout. + type: string + format: date-time + examples: + - '2025-01-15T14:00:00Z' + organization_id: + description: Organization ID for the user's most recently active organization within this session. This represents the primary organization context for the current session. + type: string + examples: + - org_1234567890123456 + session_id: + description: Unique identifier for the session. System-generated read-only field used to reference this session. + type: string + examples: + - ses_1234567890123456 + status: + description: 'Current operational status of the session. Possible values: ''active'' (session is valid and requests are allowed), ''expired'' (session terminated due to idle or absolute timeout), ''revoked'' (session was administratively revoked), ''logout'' (user explicitly logged out). Use this to determine if the session can be used for new requests.' + type: string + examples: + - active + updated_at: + description: Timestamp indicating when the session was last updated. Updated whenever session state changes such as organization context changes or metadata updates. + type: string + format: date-time + examples: + - '2025-01-15T10:45:00Z' + user_id: + description: Unique identifier for the user who owns and is authenticated within this session. + type: string + examples: + - usr_1234567890123456 + sessionsRevokedSessionDetails: + type: object + properties: + absolute_expires_at: + description: The absolute expiration timestamp that was configured for this session before revocation. Represents the hard deadline regardless of activity. + type: string + format: date-time + examples: + - '2025-01-22T10:30:00Z' + created_at: + description: Timestamp indicating when the session was originally created before revocation. + type: string + format: date-time + examples: + - '2025-01-15T10:30:00Z' + expired_at: + description: Timestamp when the session was actually terminated. Set to the revocation time when the session is revoked. + type: string + format: date-time + examples: + - '2025-01-15T12:00:00Z' + idle_expires_at: + description: The idle expiration timestamp that was configured for this session before revocation. Represents when the session would have expired due to inactivity. + type: string + format: date-time + examples: + - '2025-01-15T11:30:00Z' + last_active_at: + description: Timestamp of the last recorded user activity in this session before revocation. Helps identify inactive sessions that were revoked. + type: string + format: date-time + examples: + - '2025-01-15T10:55:30Z' + logout_at: + description: Timestamp when the user explicitly logged out (if applicable). Null if the session was revoked without prior logout. + type: string + format: date-time + examples: + - '2025-01-15T14:00:00Z' + session_id: + description: Unique identifier for the revoked session. System-generated read-only field. + type: string + examples: + - ses_1234567890123456 + status: + description: Status of the session after revocation. Always 'revoked' since only active sessions can be revoked. Sessions that were already expired or logged out are not included in the revocation response. + type: string + examples: + - revoked + updated_at: + description: Timestamp indicating when the session was last modified before revocation. + type: string + format: date-time + examples: + - '2025-01-15T10:45:00Z' + user_id: + description: Unique identifier for the user who owned this session. + type: string + examples: + - usr_1234567890123456 + sessionsRevokeSessionResponse: + type: object + properties: + revoked_session: + description: Details of the revoked session including session ID, user ID, creation and revocation timestamps, and final device information. + $ref: '#/components/schemas/sessionsRevokedSessionDetails' + usersListUsersResponse: + type: object + properties: + next_page_token: + description: Token for retrieving the next page of results. Empty if there are no more pages. + type: string + examples: + - eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0= + prev_page_token: + description: Token for retrieving the previous page of results. Empty if this is the first page. + type: string + examples: + - eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9 + total_size: + description: Total number of users matching the request criteria, regardless of pagination. + type: integer + format: int64 + examples: + - 1042 + users: + description: List of users. + type: array + items: + type: object + $ref: '#/components/schemas/usersUser' + usersGetUserResponse: + type: object + properties: + user: + $ref: '#/components/schemas/usersUser' + usersUpdateUserProfile: + type: object + properties: + custom_attributes: + description: Updates custom attributes for extended user profile data and application-specific information. Use this field to store business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + type: object + additionalProperties: + type: string + examples: + - department: engineering + security_clearance: level2 + family_name: + description: Updates the user's family name (last name or surname). Use this field to modify how the user's last name appears throughout the system. Maximum 255 characters allowed. + type: string + examples: + - Doe + first_name: + description: '[DEPRECATED] Use given_name instead. User''s given name. Maximum 200 characters.' + type: string + examples: + - John + gender: + description: Updates the user's gender identity information. Use this field to store the user's gender identity for personalization, compliance, or reporting purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies. + type: string + examples: + - male + given_name: + description: Updates the user's given name (first name). Use this field to modify how the user's first name appears in the system and user interfaces. Maximum 255 characters allowed. + type: string + examples: + - John + groups: + description: Updates the list of group names the user belongs to within the organization. Use this field to manage the user's group memberships for role-based access control, team assignments, or organizational structure. Groups are typically used for permission management and collaborative access. Each group name must be unique within the list, 1-250 characters long, with a maximum of 50 groups per user. + type: array + items: + type: string + examples: + - - engineering + - managers + last_name: + description: '[DEPRECATED] Use family_name instead. User''s family name. Maximum 200 characters.' + type: string + examples: + - Doe + locale: + description: Updates the user's preferred language and region settings using BCP-47 format codes. Use this field to customize the user's experience with localized content, date formats, number formatting, and UI language. When not specified, the user inherits the organization's default locale settings. Common values include `en-US`, `en-GB`, `fr-FR`, `de-DE`, and `es-ES`. + type: string + examples: + - en-US + metadata: + description: Updates system-managed key-value pairs for internal tracking and operational data. Use this field to store system-generated metadata like account status, signup source, last activity tracking, or integration-specific identifiers. These fields are typically managed by automated processes rather than direct user input. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + type: object + additionalProperties: + type: string + examples: + - account_status: active + signup_source: mobile_app + name: + description: Updates the user's complete display name. Use this field when you want to set the full name as a single string rather than using separate given and family names. This name appears in user interfaces, reports, and anywhere a formatted display name is needed. + type: string + examples: + - John Doe + phone_number: + description: Updates the user's phone number in E.164 international format. Use this field to enable SMS-based authentication methods, two-factor authentication, or phone-based account recovery. The phone number must include the country code and be formatted according to E.164 standards (e.g., `+1` for US numbers). This field is required when enabling SMS authentication features. + type: string + examples: + - '+14155552671' + picture: + description: Updates the URL to the user's profile picture or avatar image. Use this field to set or change the user's profile photo that appears in user interfaces, directory listings, and collaborative features. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. Maximum URL length is 2048 characters. + type: string + examples: + - https://example.com/avatar.jpg + preferred_username: + description: Updates the user's preferred username for display and identification purposes. Use this field to set a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, and informal communications. Maximum 512 characters allowed. + type: string + examples: + - John Michael Doe + v1usersUpdateUser: + type: object + properties: + external_id: + description: Your application's unique identifier for this organization, used to link Scalekit with your system. + type: string + examples: + - ext_12345a67b89c + metadata: + description: Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + type: object + additionalProperties: + type: string + examples: + - department: engineering + location: nyc-office + user_profile: + description: User's personal information including name, address, and other profile attributes. + $ref: '#/components/schemas/usersUpdateUserProfile' + usersUpdateUserResponse: + type: object + properties: + user: + $ref: '#/components/schemas/usersUser' + sessionsUserSessionDetails: + type: object + properties: + next_page_token: + description: Pagination token for retrieving the next page of results. Empty string if there are no more pages (you have reached the final page of results). + type: string + examples: + - eyJwYWdlIjogMiwgImxhc3RfaWQiOiAic2VzXzEyMzQ1In0= + prev_page_token: + description: Pagination token for retrieving the previous page of results. Empty string for the first page. Use this to navigate backward through result pages. + type: string + examples: + - eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInNlc183OTAxIn0= + sessions: + description: Array of session objects for the requested user. May contain fewer entries than the requested page_size when reaching the final page of results. + type: array + items: + type: object + $ref: '#/components/schemas/sessionsSessionDetails' + total_size: + description: Total number of sessions matching the applied filter criteria, regardless of pagination. This represents the complete result set size before pagination is applied. + type: integer + format: int64 + examples: + - 42 + sessionsRevokeAllUserSessionsResponse: + type: object + properties: + revoked_sessions: + description: List of all sessions that were revoked, including detailed information for each revoked session with IDs, timestamps, and device details. + type: array + items: + type: object + $ref: '#/components/schemas/sessionsRevokedSessionDetails' + total_revoked: + description: Total count of active sessions that were revoked. Useful for confirmation and audit logging. + type: integer + format: int64 + examples: + - 5 + usersSearchUsersResponse: + type: object + properties: + next_page_token: + description: Token for retrieving the next page of results. Empty if there are no more pages. + type: string + examples: + - eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0= + prev_page_token: + description: Token for retrieving the previous page of results. Empty if this is the first page. + type: string + examples: + - eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9 + total_size: + description: Total number of users matching the request criteria, regardless of pagination. + type: integer + format: int64 + examples: + - 1042 + users: + description: List of matching users. + type: array + items: + type: object + $ref: '#/components/schemas/usersUser' + webauthnAllAcceptedCredentialsOptions: + type: object + properties: + all_accepted_credential_ids: + description: List of credential IDs the user can authenticate with + type: array + items: + type: string + rp_id: + description: Relying Party ID for credential operations + type: string + examples: + - example.com + user_id: + description: User ID for credential verification + type: string + examples: + - user_xyz789 + WebAuthnCredentialAuthenticator: + type: object + properties: + aaguid: + description: Authenticator Attestation GUID (AAGUID) identifying the device model + type: string + attachment: + description: 'Attachment type: "platform" (built-in) or "cross-platform"' + type: string + examples: + - platform + icon_dark: + description: Icon URL for dark theme display + type: string + icon_light: + description: Icon URL for light theme display + type: string + name: + description: Human-readable name of the authenticator model + type: string + examples: + - Apple Touch ID + WebAuthnCredentialAuthenticatorFlags: + type: object + properties: + backup_eligible: + description: Whether this credential can be backed up to another device + type: boolean + backup_state: + description: Whether this credential was synced or backed up + type: boolean + user_present: + description: Whether the user was present during authentication + type: boolean + user_verified: + description: Whether the user was verified (e.g., fingerprint, PIN) + type: boolean + WebAuthnCredentialClientInfo: + type: object + properties: + city: + description: City name + type: string + examples: + - San Francisco + ip: + description: IP address from which credential was registered + type: string + examples: + - 192.0.2.1 + region: + description: Geographic region (e.g., "US") + type: string + examples: + - US + region_subdivision: + description: Regional subdivision (e.g., "CA") + type: string + examples: + - CA + WebAuthnCredentialUserAgent: + type: object + properties: + browser: + description: Browser name (e.g., "Chrome", "Safari") + type: string + examples: + - Chrome + browser_version: + description: Browser version number + type: string + examples: + - 120.0.6099.129 + device_model: + description: Device model if available + type: string + examples: + - iPhone15,2 + device_type: + description: 'Device type: "desktop", "mobile", or "tablet"' + type: string + examples: + - mobile + os: + description: Operating system name (e.g., "Windows", "iOS") + type: string + examples: + - macOS + os_version: + description: Operating system version + type: string + examples: + - '14.2' + raw: + description: Raw user agent string from the browser + type: string + url: + description: Parsed user agent URL reference + type: string + webauthnWebAuthnCredential: + type: object + properties: + attestation_type: + description: 'Type of attestation: "none", "indirect", or "direct"' + type: string + examples: + - direct + authenticator: + description: Authenticator information including model and name + $ref: '#/components/schemas/WebAuthnCredentialAuthenticator' + authenticator_flags: + description: Flags indicating authenticator capabilities + $ref: '#/components/schemas/WebAuthnCredentialAuthenticatorFlags' + client_info: + description: Geographic and network information from registration + $ref: '#/components/schemas/WebAuthnCredentialClientInfo' + created_at: + description: Timestamp when the credential was created + type: string + format: date-time + examples: + - '2025-02-15T06:23:44.560000Z' + credential_id: + description: The actual credential ID bytes from the authenticator + type: string + contentEncoding: base64 + display_name: + description: Optional user-friendly name for this passkey + type: string + examples: + - My Yubikey + id: + description: Credential unique identifier + type: string + examples: + - cred_abc123 + transports: + description: Supported transports for this credential + type: array + items: + type: string + updated_at: + description: Timestamp of last update + type: string + format: date-time + examples: + - '2025-02-15T06:23:44.560000Z' + user_agent: + description: Browser and device information from registration + $ref: '#/components/schemas/WebAuthnCredentialUserAgent' + user_id: + description: User ID this credential belongs to + type: string + examples: + - user_xyz789 + webauthnListCredentialsResponse: + type: object + properties: + all_accepted_credentials_options: + description: Options including RP ID and all accepted credential IDs for authentication + $ref: '#/components/schemas/webauthnAllAcceptedCredentialsOptions' + credentials: + description: All passkeys registered for the user + type: array + items: + type: object + $ref: '#/components/schemas/webauthnWebAuthnCredential' + webauthnUnknownCredentialOptions: + type: object + properties: + credential_id: + description: The deleted credential ID + type: string + examples: + - cred_abc123 + rp_id: + description: The RP ID for this credential + type: string + examples: + - example.com + webauthnDeleteCredentialResponse: + type: object + properties: + success: + description: Whether the credential was successfully deleted + type: boolean + examples: + - true + unknown_credential_options: + description: Options for handling unknown credentials in client applications + $ref: '#/components/schemas/webauthnUnknownCredentialOptions' + WebAuthnServiceUpdateCredentialBody: + type: object + properties: + display_name: + description: Human-friendly name for this credential (1-120 characters) + type: string + examples: + - My iPhone 15 Pro + webauthnUpdateCredentialResponse: + type: object + properties: + credential: + description: The updated credential with new display name + $ref: '#/components/schemas/webauthnWebAuthnCredential' + ScalekitEvent: + type: object + required: + - spec_version + - id + - type + - occurred_at + - environment_id + - object + properties: + spec_version: + type: string + example: '1' + description: The webhook specification version + pattern: ^[0-9]+$ + id: + type: string + pattern: ^evt_ + example: evt_1234567890abcdef + description: Unique identifier for the webhook event (must be prefixed with "evt_") + minLength: 1 + maxLength: 32 + type: + type: string + example: organization.created + description: The event type + enum: + - organization.created + - organization.updated + - organization.deleted + - organization.sso_created + - organization.sso_deleted + - organization.sso_enabled + - organization.sso_disabled + - user.signup + - user.login + - user.logout + - user.organization_invitation + - user.organization_membership_created + - user.organization_membership_updated + - user.organization_membership_deleted + - organization.directory.user_created + - organization.directory.user_updated + - organization.directory.user_deleted + - organization.directory.group_created + - organization.directory.group_updated + - organization.directory.group_deleted + - organization.directory_enabled + - organization.directory_disabled + - role.created + - role.updated + - role.deleted + - permission.created + - permission.updated + - permission.deleted + occurred_at: + type: string + format: date-time + description: When the event occurred (ISO 8601 format) + example: '2024-01-01T00:00:00Z' + environment_id: + type: string + pattern: ^env_ + example: env_1234567890abcdef + description: The environment ID where the event occurred + minLength: 1 + maxLength: 32 + organization_id: + type: string + pattern: ^org_ + example: org_1234567890abcdef + description: The organization ID (if applicable) + minLength: 1 + maxLength: 32 + object: + type: string + description: The type of object that triggered the webhook + enum: + - Organization + - Connection + - Role + - Directory + - DirectoryUser + - DirectoryGroup + - Permission + - OrgMembership + - User + example: Organization + data: + type: object + description: The event payload (structure varies by event type) + additionalProperties: true + example: + id: org_1234567890abcdef + name: Example Organization + created_at: '2024-01-01T00:00:00Z' + display_name: + type: string + description: Human-readable display name for the event + example: Organization Created + minLength: 1 + maxLength: 200 +x-scalar-environments: + production: + variables: + SCALEKIT_ENVIRONMENT_URL: + default: https://$SCALEKIT_ENVIRONMENT_URL + description: yourapp.scalekit.com + staging: + variables: + SCALEKIT_ENVIRONMENT_URL: + default: https://$SCALEKIT_ENVIRONMENT_URL + description: yourapp.scalekit.dev +x-scalar-active-environment: staging diff --git a/public/apis.md b/public/apis.md new file mode 100644 index 000000000..a19a8a7ec --- /dev/null +++ b/public/apis.md @@ -0,0 +1,26635 @@ +# Scalekit APIs + +- **OpenAPI Version:** `3.1.1` +- **API Version:** `1.0.0` + +# Overview + +The Scalekit API is a RESTful API that enables you to manage organizations, users, and authentication settings. All requests must use HTTPS. All API requests use the following base URLs: + +```properties +https://{your-subdomain}.scalekit.dev (Development) +https://{your-subdomain}.scalekit.com (Production) +https://auth.yourapp.com (Custom domain) +``` + +Scalekit operates two separate environments: Development and Production. Resources cannot be moved between environments. + +## Quickstart + +The Scalekit API uses OAuth 2.0 Client Credentials for authentication. + +Copy your API credentials from the Scalekit dashboard's API Config section and set them as environment variables. + +```sh +SCALEKIT_ENVIRONMENT_URL='' +SCALEKIT_CLIENT_ID='' +SCALEKIT_CLIENT_SECRET='' +``` + +Getting an access token + +1. Get your credentials from the [Scalekit Dashboard](https://app.scalekit.com) +2. Request an access token: + +```sh +curl https:///oauth/token \ + -X POST \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'client_id={client_id}' \ + -d 'client_secret={client_secret}' \ + -d 'grant_type=client_credentials' +``` + +3. Use the access token in API requests: + +```sh +curl https:///api/v1/organizations \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {access_token}' +``` + +The response includes an access token: + +```json +{ + "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNua181Ok4OTEyMjU2NiIsInR5cCI6IkpXVCJ9...", + "token_type": "Bearer", + "expires_in": 86399, + "scope": "openid" +} +``` + +## SDKs + +Scalekit provides official SDKs for multiple programming languages. Check the changelog at GitHub repositories for the latest updates. + +### Node.js + +```sh +npm install @scalekit-sdk/node +``` + +Create a new Scalekit client instance after initializing the environment variables + +```js +import { Scalekit } from "@scalekit-sdk/node"; + +export let scalekit = new Scalekit( + process.env.SCALEKIT_ENVIRONMENT_URL, + process.env.SCALEKIT_CLIENT_ID, + process.env.SCALEKIT_CLIENT_SECRET +); +``` + +[See the Node SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-node/releases) + +### Python + +```sh +pip install scalekit-sdk-python +``` + +Create a new Scalekit client instance after initializing the environment variables. + +```py +from scalekit import ScalekitClient +import os + +scalekit_client = ScalekitClient( + os.environ.get('SCALEKIT_ENVIRONMENT_URL'), + os.environ.get('SCALEKIT_CLIENT_ID'), + os.environ.get('SCALEKIT_CLIENT_SECRET') +) +``` + +[See the Python SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-python/releases) + +### Go + +```sh +go get -u github.com/scalekit-inc/scalekit-sdk-go +``` + +Create a new Scalekit client instance after initializing the environment variables. + +```go +package main + +import ( + "os" + "github.com/scalekit-inc/scalekit-sdk-go" +) + +scalekitClient := scalekit.NewScalekitClient( + os.Getenv("SCALEKIT_ENVIRONMENT_URL"), + os.Getenv("SCALEKIT_CLIENT_ID"), + os.Getenv("SCALEKIT_CLIENT_SECRET"), +) +``` + +[See the Go SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-go/releases) + +### Java + +```gradle +/* Gradle users - add the following to your dependencies in build file */ +implementation "com.scalekit:scalekit-sdk-java:2.0.11" +``` + +```xml + + + com.scalekit + scalekit-sdk-java + 2.0.11 + +``` + +[See the Java SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-java/releases) + +### Error handling + +The API uses standard HTTP status codes: + +| Code | Description | +| ----------- | -------------------- | +| 200/201 | Success | +| 400 | Invalid request | +| 401 | Authentication error | +| 404 | Resource not found | +| 429 | Rate limit exceeded | +| 500/501/504 | Server error | + +Error responses include detailed information: + +```json +{ + "code": 16, + "message": "Token empty", + "details": [ + { + "@type": "type.googleapis.com/scalekit.v1.errdetails.ErrorInfo", + "error_code": "UNAUTHENTICATED" + } + ] +} +``` + +## Servers + +- **URL:** `https://$SCALEKIT_ENVIRONMENT_URL` + +## Operations + +### List connected accounts + +- **Method:** `GET` +- **Path:** `/api/v1/connected_accounts` +- **Tags:** Connected Accounts + +Retrieves a paginated list of connected accounts for third-party integrations. Filter by organization, user, connector type, provider, or identifier. Returns OAuth tokens, API keys, and connection status for each account. Use pagination tokens to navigate through large result sets. + +#### Responses + +##### Status: 200 Successfully retrieved the list of connected accounts with their authentication details and status + +###### Content-Type: application/json + +- **`connected_accounts`** + + `array` — List of connected accounts matching the filter criteria. Excludes sensitive authorization details for security. + + **Items:** + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Authorization mechanism type. + + - **`connection_id`** + + `string` — Parent connection configuration reference. + + - **`connector`** + + `string` — Connector identifier. + + - **`id`** + + `string` — Unique connected account identifier. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. + + - **`last_used_at`** + + `string`, format: `date-time` — Last usage timestamp. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft'). + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current connection status. + + - **`token_expires_at`** + + `string`, format: `date-time` — Token expiration timestamp. + + - **`updated_at`** + + `string`, format: `date-time` — Last modification timestamp. + +- **`next_page_token`** + + `string` — Pagination token for retrieving the next page. Empty if this is the last page. Pass this value to page\_token in the next request. + +- **`prev_page_token`** + + `string` — Pagination token for retrieving the previous page. Empty if this is the first page. Pass this value to page\_token to go back. + +- **`total_size`** + + `integer`, format: `int64` — Total count of connected accounts matching the filter criteria across all pages. Use for calculating pagination. + +**Example:** + +```json +{ + "connected_accounts": [ + { + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } + ], + "next_page_token": "eyJvZmZzZXQiOjIwfQ==", + "prev_page_token": "eyJvZmZzZXQiOjB9", + "total_size": 100 +} +``` + +##### Status: 400 Invalid request - occurs when query parameters are malformed or validation fails + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Update connected account credentials + +- **Method:** `PUT` +- **Path:** `/api/v1/connected_accounts` +- **Tags:** Connected Accounts + +Updates authentication credentials and configuration for an existing connected account. Modify OAuth tokens, refresh tokens, access scopes, or API configuration settings. Specify the account by ID, or by combination of organization/user, connector, and identifier. Returns the updated account with new token expiry and status information. + +#### Request Body + +##### Content-Type: application/json + +- **`connected_account`** + + `object` — Details of the connected account to update + + - **`api_config`** + + `object` — Updated JSON configuration for API-specific settings. Merges with existing configuration - only provided fields are modified. + + - **`authorization_details`** + + `object` — Updated authentication credentials. Provide new OAuth tokens (e.g., after refresh) or updated static auth details. Only included fields will be modified. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +- **`connector`** + + `string` — Connector identifier + +- **`id`** + + `string` — Unique identifier for the connected account to update + +- **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +- **`organization_id`** + + `string` — Organization ID for the connector + +- **`user_id`** + + `string` — User ID for the connector + +**Example:** + +```json +{ + "connected_account": { + "authorization_details": { + "oauth_token": { + "access_token": "...", + "refresh_token": "...", + "scopes": [ + "read", + "write" + ] + } + }, + "authorization_type": "OAUTH2" + }, + "connector": "notion", + "id": "ca_123", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "user_id": "user_121312434123312" +} +``` + +#### Responses + +##### Status: 200 Connected account updated successfully with new credentials or configuration + +###### Content-Type: application/json + +- **`connected_account`** + + `object` — The updated connected account with refreshed credentials, new token expiry, and modified configuration settings. + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. + + - **`authorization_details`** + + `object` — Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. + + - **`connection_id`** + + `string` — Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. + + - **`connector`** + + `string` — Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to. + + - **`id`** + + `string` — Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca\_'. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier. + + - **`last_used_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection. + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. + + - **`token_expires_at`** + + `string`, format: `date-time` — Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. + +**Example:** + +```json +{ + "connected_account": { + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": null, + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } +} +``` + +##### Status: 400 Invalid request - missing required fields, invalid authorization details, or validation failed + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 404 Connected account not found - the specified account does not exist + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Create a connected account + +- **Method:** `POST` +- **Path:** `/api/v1/connected_accounts` +- **Tags:** Connected Accounts + +Creates a new connected account with OAuth tokens or API credentials for third-party service integration. Supply authorization details including access tokens, refresh tokens, scopes, and optional API configuration. The account can be scoped to an organization or user. Returns the created account with its unique identifier and authentication status. + +#### Request Body + +##### Content-Type: application/json + +- **`connected_account`** + + `object` — Details of the connected account to create + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom API endpoints, timeouts, or feature flags. + + - **`authorization_details`** + + `object` — Optional authentication credentials for the connected account. Include OAuth tokens (access\_token, refresh\_token, scopes) or static auth details (API keys, bearer tokens). Can be provided later via update. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +- **`connector`** + + `string` — Connector identifier + +- **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +- **`organization_id`** + + `string` — Organization ID for the connector + +- **`user_id`** + + `string` — User ID for the connector + +**Example:** + +```json +{ + "connected_account": { + "authorization_details": { + "oauth_token": { + "access_token": "...", + "refresh_token": "...", + "scopes": [ + "read", + "write" + ] + } + }, + "authorization_type": "OAUTH2" + }, + "connector": "notion", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "user_id": "user_121312434123312" +} +``` + +#### Responses + +##### Status: 201 Connected account created successfully with authentication credentials stored securely + +###### Content-Type: application/json + +- **`connected_account`** + + `object` — The newly created connected account with its unique identifier, status, and complete authorization details including access tokens. + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. + + - **`authorization_details`** + + `object` — Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. + + - **`connection_id`** + + `string` — Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. + + - **`connector`** + + `string` — Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to. + + - **`id`** + + `string` — Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca\_'. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier. + + - **`last_used_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection. + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. + + - **`token_expires_at`** + + `string`, format: `date-time` — Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. + +**Example:** + +```json +{ + "connected_account": { + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": null, + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } +} +``` + +##### Status: 400 Invalid request - missing required fields, invalid authorization details, or validation failed + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 409 Conflict - connected account with the same identifier already exists + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Get connected account details + +- **Method:** `GET` +- **Path:** `/api/v1/connected_accounts/auth` +- **Tags:** Connected Accounts + +Retrieves complete authentication details for a connected account including OAuth tokens, refresh tokens, scopes, and API configuration. Query by account ID or by combination of organization/user, connector, and identifier. Returns sensitive credential information - use appropriate access controls. + +#### Responses + +##### Status: 200 Successfully retrieved connected account with full authentication details + +###### Content-Type: application/json + +- **`connected_account`** + + `object` — The connected account with complete details including sensitive authorization credentials (access tokens, refresh tokens, scopes). Handle with appropriate access controls. + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. + + - **`authorization_details`** + + `object` — Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. + + - **`connection_id`** + + `string` — Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. + + - **`connector`** + + `string` — Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to. + + - **`id`** + + `string` — Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca\_'. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier. + + - **`last_used_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection. + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. + + - **`token_expires_at`** + + `string`, format: `date-time` — Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. + +**Example:** + +```json +{ + "connected_account": { + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": null, + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } +} +``` + +##### Status: 400 Invalid request - missing required query parameters + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 404 Connected account not found - no account matches the specified criteria + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Generate authentication magic link + +- **Method:** `POST` +- **Path:** `/api/v1/connected_accounts/magic_link` +- **Tags:** Connected Accounts + +Creates a time-limited magic link for connecting or re-authorizing a third-party account. The link directs users to the OAuth authorization flow for the specified connector. Returns the generated link URL and expiration timestamp. Links typically expire after a short duration for security. + +#### Request Body + +##### Content-Type: application/json + +- **`connector`** + + `string` — Connector identifier + +- **`id`** + + `string` — Unique identifier for the connected account + +- **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +- **`organization_id`** + + `string` — Organization ID for the connector + +- **`state`** + + `string` — Optional opaque state value. State added to the user verify redirect URL query params to validate the user verification + +- **`user_id`** + + `string` — User ID for the connector + +- **`user_verify_url`** + + `string` — B2B app's user verify redirect URL + +**Example:** + +```json +{ + "connector": "notion", + "id": "ca_123", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "state": "QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY=", + "user_id": "user_121312434123312", + "user_verify_url": "https://app.yourapp.com/user/verify/callback" +} +``` + +#### Responses + +##### Status: 200 Magic link generated successfully with authorization URL and expiry time + +###### Content-Type: application/json + +- **`expiry`** + + `string`, format: `date-time` — Expiry timestamp for the authentication link + +- **`link`** + + `string` — Authentication link for the connector + +**Example:** + +```json +{ + "expiry": "2024-03-20T15:04:05Z", + "link": "https://notion.com/oauth/authorize?client_id=..." +} +``` + +##### Status: 400 Invalid request - missing required parameters or invalid connector + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Verify connected account user + +- **Method:** `POST` +- **Path:** `/api/v1/connected_accounts/user/verify` +- **Tags:** Connected Accounts + +Confirms the user assertion and activates the connected account after the user completes third-party OAuth. Called by the B2B app server with auth\_request\_id and identifier. Validates that the asserted identifier matches the one stored on the auth request and promotes pending tokens to live. + +#### Request Body + +##### Content-Type: application/json + +- **`auth_request_id` (required)** + + `string` — Auth request ID as base64url-encoded opaque token from the user verify redirect URL query params + +- **`identifier` (required)** + + `string` — Current logged in user's connected account identifier + +**Example:** + +```json +{ + "auth_request_id": "QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY=", + "identifier": "user@example.com" +} +``` + +#### Responses + +##### Status: 200 Verification successful; connected account is now ACTIVE + +###### Content-Type: application/json + +- **`post_user_verify_redirect_url`** + + `string` — URL to redirect the user to after successful verification + +**Example:** + +```json +{ + "post_user_verify_redirect_url": "https://env1.example.com/connect/success" +} +``` + +##### Status: 400 Invalid request - missing or malformed fields + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Unauthorized - invalid or missing access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 403 Forbidden - identifier mismatch + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 404 Not found - no pending flow for the given auth\_request\_id or already consumed + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Delete a connected account + +- **Method:** `POST` +- **Path:** `/api/v1/connected_accounts:delete` +- **Tags:** Connected Accounts + +Permanently removes a connected account and revokes all associated authentication credentials. Identify the account by ID, or by combination of organization/user, connector, and identifier. This action cannot be undone. All OAuth tokens and API keys for this account will be invalidated. + +#### Request Body + +##### Content-Type: application/json + +- **`connector`** + + `string` — Connector identifier + +- **`id`** + + `string` — Unique identifier for the connected account to delete + +- **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +- **`organization_id`** + + `string` — Organization ID for the connector + +- **`user_id`** + + `string` — User ID for the connector + +**Example:** + +```json +{ + "connector": "notion", + "id": "ca_123", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "user_id": "user_121312434123312" +} +``` + +#### Responses + +##### Status: 200 Connected account deleted successfully and all credentials revoked + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 400 Invalid request - malformed parameters or validation failed + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 404 Connected account not found - the specified account does not exist + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Search connected accounts + +- **Method:** `GET` +- **Path:** `/api/v1/connected_accounts:search` +- **Tags:** Connected Accounts + +Search for connected accounts in your environment using a text query that matches against identifiers, providers, or connectors. The search performs case-insensitive matching across account details. Returns paginated results with account status and authentication type information. + +#### Responses + +##### Status: 200 Successfully retrieved matching connected accounts with pagination support + +###### Content-Type: application/json + +- **`connected_accounts`** + + `array` — List of connected accounts matching the search query. Excludes sensitive authorization details. + + **Items:** + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Authorization mechanism type. + + - **`connection_id`** + + `string` — Parent connection configuration reference. + + - **`connector`** + + `string` — Connector identifier. + + - **`id`** + + `string` — Unique connected account identifier. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. + + - **`last_used_at`** + + `string`, format: `date-time` — Last usage timestamp. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft'). + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current connection status. + + - **`token_expires_at`** + + `string`, format: `date-time` — Token expiration timestamp. + + - **`updated_at`** + + `string`, format: `date-time` — Last modification timestamp. + +- **`next_page_token`** + + `string` — Pagination token for the next page. Empty if this is the last page. + +- **`prev_page_token`** + + `string` — Pagination token for the previous page. Empty if this is the first page. + +- **`total_size`** + + `integer`, format: `int64` — Total count of accounts matching the search query across all pages. + +**Example:** + +```json +{ + "connected_accounts": [ + { + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } + ], + "next_page_token": "eyJvZmZzZXQiOjMwfQ==", + "prev_page_token": "eyJvZmZzZXQiOjB9", + "total_size": 100 +} +``` + +##### Status: 400 Invalid request - query parameter is too short (minimum 3 characters) or validation failed + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### List connections + +- **Method:** `GET` +- **Path:** `/api/v1/connections` +- **Tags:** Connections + +Retrieves a list of connections in the environment + +#### Responses + +##### Status: 200 Successfully retrieved connections + +###### Content-Type: application/json + +- **`connections`** + + `array` — List of connections matching the request criteria + + **Items:** + + - **`domains`** + + `array` — List of domains configured with this connection + + **Items:** + + `string` + + - **`enabled`** + + `boolean` — Whether the connection is currently active for organization users + + - **`id`** + + `string` — Unique identifier of the connection + + - **`key_id`** + + `string` — Alternative identifier for this connection, typically used in frontend applications or URLs + + - **`organization_id`** + + `string` — Unique identifier of the organization that owns this connection + + - **`organization_name`** + + `string` — Name of the organization of the connection + + - **`provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Identity provider type (e.g., OKTA, Google, Azure AD) + + - **`provider_key`** + + `string` — Key ID of the identity provider service that handles authentication + + - **`status`** + + `string`, possible values: `"DRAFT", "IN_PROGRESS", "COMPLETED"` — Current configuration status of the connection + + - **`type`** + + `string`, possible values: `"OIDC", "SAML", "PASSWORD", "OAUTH", "PASSWORDLESS", "BASIC", "BEARER", "API_KEY", "WEBAUTHN"` — Authentication protocol used by the connection + +**Example:** + +```json +{ + "connections": [ + { + "domains": [ + "yourapp.com", + "yourworkspace.com" + ], + "enabled": false, + "id": "conn_2123312131125533", + "key_id": "conn_2123312131125533", + "organization_id": "org_2123312131125533", + "organization_name": "Your Organization", + "provider": "CUSTOM", + "provider_key": "google", + "status": "IN_PROGRESS", + "type": "OIDC" + } + ] +} +``` + +### Execute a tool using a connected account + +- **Method:** `POST` +- **Path:** `/api/v1/execute_tool` +- **Tags:** Connected Accounts + +Executes a tool action using authentication credentials from a connected account. Specify the tool by name and provide required parameters as JSON. The connected account can be identified by ID, or by combination of organization/user, connector, and identifier. Returns the execution result data and a unique execution ID for tracking. Use this endpoint to perform actions like sending emails, creating calendar events, or managing resources in external services. + +#### Request Body + +##### Content-Type: application/json + +- **`connected_account_id`** + + `string` — Optional. The unique ID of the connected account. Use this to directly identify the connected account instead of using identifier + connector combination. + +- **`connector`** + + `string` — Optional. The name of the connector/provider (e.g., 'Google Workspace', 'Slack', 'Notion'). Use this in combination with identifier to identify the connected account. + +- **`identifier`** + + `string` — Optional. The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). Use this in combination with connector to identify the connected account. + +- **`organization_id`** + + `string` — Optional. The organization ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple organizations. + +- **`params`** + + `object` — JSON object containing the parameters required for tool execution. The structure depends on the specific tool being executed. + +- **`tool_name`** + + `string` — Name of the tool to execute + +- **`user_id`** + + `string` — Optional. The user ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple users. + +**Example:** + +```json +{ + "connected_account_id": "ca_123", + "connector": "Google Workspace", + "identifier": "user@example.com", + "organization_id": "org_123", + "params": { + "body": "Hello World", + "subject": "Hello", + "to": "user@example.com" + }, + "tool_name": "send_email", + "user_id": "user_123" +} +``` + +#### Responses + +##### Status: 200 Tool executed successfully with result data and execution ID + +###### Content-Type: application/json + +- **`data`** + + `object` — Free-flowing JSON parameters for the tool execution + +- **`execution_id`** + + `string` — Unique identifier for the tool execution + +**Example:** + +```json +{ + "data": { + "body": "Hello World", + "subject": "Hello", + "to": "user@example.com" + }, + "execution_id": "123456789" +} +``` + +##### Status: 400 Invalid request - occurs when tool name is missing, parameters are malformed, or tool definition validation fails + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 401 Authentication required - missing or invalid access token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 404 Tool or connected account not found - occurs when the specified tool name or connected account does not exist + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 500 Tool execution failed - occurs when the external service returns an error or the tool encounters a runtime exception + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Resend user invitation email + +- **Method:** `PATCH` +- **Path:** `/api/v1/invites/organizations/{organization_id}/users/{id}/resend` +- **Tags:** Users + +Resends an invitation email to a user who has a pending or expired invitation in the specified organization. If the invitation has expired, a new invitation will be automatically created and sent. If the invitation is still valid, a reminder email will be sent instead. Use this endpoint when a user hasn't responded to their initial invitation and you need to send them a reminder or when the original invitation has expired. The invitation email includes a secure magic link that allows the user to complete their account setup and join the organization. Each resend operation increments the resent counter. + +#### Request Body + +##### Content-Type: application/json + +**Example:** + +```json +{} +``` + +#### Responses + +##### Status: 200 Successfully resent the invitation email. Returns the updated invitation object with organization ID, user ID, membership status, timestamps, and resent count. If expired, a new invitation is created; otherwise, the existing one is resent. + +###### Content-Type: application/json + +- **`invite`** + + `object` — Updated invitation object containing the resent invitation details, including new expiration time and incremented resend counter. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invite was originally created. + + - **`expires_at`** + + `string`, format: `date-time` — The time at which the invite expires. + + - **`inviter_email`** + + `string` — Identifier of the user or system that initiated the invite. + + - **`organization_id`** + + `string` — The organization to which the invite belongs. + + - **`resent_at`** + + `string`, format: `date-time` — Timestamp when the invite was last resent, if applicable. + + - **`resent_count`** + + `integer`, format: `int32` — Number of times the invite has been resent. + + - **`status`** + + `string` — Current status of the invite (e.g., pending, accepted, expired, revoked). + + - **`user_id`** + + `string` — User ID to whom the invite is sent. May be empty if the user has not signed up yet. + +**Example:** + +```json +{ + "invite": { + "expires_at": "2025-12-31T23:59:59Z", + "organization_id": "org_123", + "resent_count": 2, + "status": "pending_invite", + "user_id": "usr_456" + } +} +``` + +##### Status: 400 Invalid request — common causes include user ID or organization ID is invalid, full-stack authentication is disabled, user profile is missing, invite already accepted, or missing expiry time in user management settings. + +###### Content-Type: application/json + +- **`debug_info`** + + `object` — Describes additional debugging info. + + - **`detail`** + + `string` — Additional debugging information provided by the server. + + - **`stack_entries`** + + `array` — The stack trace entries indicating where the error occurred. + + **Items:** + + `string` + +- **`error_code`** + + `string` + +- **`help_info`** + + `object` — HelpInfo provides documentation links attached to an error response. When present in ErrorInfo, clients should surface these links to help developers resolve the error. For example, a missing required field error may include a link to the relevant guide. + + - **`links`** + + `array` — One or more links relevant to resolving the error. + + **Items:** + + - **`description`** + + `string` — Human-readable label for the link (e.g. "User verification flow"). + + - **`url`** + + `string` — Absolute URL to the documentation page (e.g. "https\://docs.scalekit.com/..."). + +- **`localized_message_info`** + + `object` + + - **`locale`** + + `string` + + - **`message`** + + `string` + +- **`request_info`** + + `object` — Contains metadata about the request that clients can attach when filing a bug or providing other forms of feedback. + + - **`request_id`** + + `string` — An opaque string that should only be interpreted by the service generating it. For example, it can be used to identify requests in the service's logs. + + - **`serving_data`** + + `string` — Any data that was used to serve this request. For example, an encrypted stack trace that can be sent back to the service provider for debugging. + +- **`resource_info`** + + `object` — Describes the resource that is being accessed. + + - **`description`** + + `string` — Describes what error is encountered when accessing this resource. For example, updating a cloud project may require the \`writer\` permission on the developer console project. + + - **`owner`** + + `string` + + - **`required_permissions`** + + `array` — The required permissions needed to access the resource. + + **Items:** + + `string` + + - **`resource_name`** + + `string` + + - **`user`** + + `string` + +- **`tool_error_info`** + + `object` + + - **`execution_id`** + + `string` + + - **`tool_error_code`** + + `string` + + - **`tool_error_message`** + + `string` + +- **`validation_error_info`** + + `object` — Describes violations in a client request. This error type focuses on the syntactic aspects of the request. + + - **`field_violations`** + + `array` — Describes all violations in a client request. + + **Items:** + + - **`constraint`** + + `string` + + - **`description`** + + `string` — A description of why the request element is bad. + + - **`field`** + + `string` + +**Example:** + +```json +{ + "debug_info": { + "detail": "", + "stack_entries": [ + "" + ] + }, + "error_code": "", + "help_info": { + "links": [ + {} + ] + }, + "localized_message_info": { + "locale": "", + "message": "" + }, + "request_info": { + "request_id": "", + "serving_data": "" + }, + "resource_info": { + "description": "", + "owner": "", + "required_permissions": [ + "" + ], + "resource_name": "", + "user": "" + }, + "tool_error_info": { + "execution_id": "", + "tool_error_code": "", + "tool_error_message": "" + }, + "validation_error_info": { + "field_violations": [ + {} + ] + } +} +``` + +##### Status: 404 Resource not found — the specified user, organization, membership, or invitation could not be found in the specified environment. Verify that all IDs are correct and that the resources exist before attempting to resend an invitation. + +###### Content-Type: application/json + +- **`debug_info`** + + `object` — Describes additional debugging info. + + - **`detail`** + + `string` — Additional debugging information provided by the server. + + - **`stack_entries`** + + `array` — The stack trace entries indicating where the error occurred. + + **Items:** + + `string` + +- **`error_code`** + + `string` + +- **`help_info`** + + `object` — HelpInfo provides documentation links attached to an error response. When present in ErrorInfo, clients should surface these links to help developers resolve the error. For example, a missing required field error may include a link to the relevant guide. + + - **`links`** + + `array` — One or more links relevant to resolving the error. + + **Items:** + + - **`description`** + + `string` — Human-readable label for the link (e.g. "User verification flow"). + + - **`url`** + + `string` — Absolute URL to the documentation page (e.g. "https\://docs.scalekit.com/..."). + +- **`localized_message_info`** + + `object` + + - **`locale`** + + `string` + + - **`message`** + + `string` + +- **`request_info`** + + `object` — Contains metadata about the request that clients can attach when filing a bug or providing other forms of feedback. + + - **`request_id`** + + `string` — An opaque string that should only be interpreted by the service generating it. For example, it can be used to identify requests in the service's logs. + + - **`serving_data`** + + `string` — Any data that was used to serve this request. For example, an encrypted stack trace that can be sent back to the service provider for debugging. + +- **`resource_info`** + + `object` — Describes the resource that is being accessed. + + - **`description`** + + `string` — Describes what error is encountered when accessing this resource. For example, updating a cloud project may require the \`writer\` permission on the developer console project. + + - **`owner`** + + `string` + + - **`required_permissions`** + + `array` — The required permissions needed to access the resource. + + **Items:** + + `string` + + - **`resource_name`** + + `string` + + - **`user`** + + `string` + +- **`tool_error_info`** + + `object` + + - **`execution_id`** + + `string` + + - **`tool_error_code`** + + `string` + + - **`tool_error_message`** + + `string` + +- **`validation_error_info`** + + `object` — Describes violations in a client request. This error type focuses on the syntactic aspects of the request. + + - **`field_violations`** + + `array` — Describes all violations in a client request. + + **Items:** + + - **`constraint`** + + `string` + + - **`description`** + + `string` — A description of why the request element is bad. + + - **`field`** + + `string` + +**Example:** + +```json +{ + "debug_info": { + "detail": "", + "stack_entries": [ + "" + ] + }, + "error_code": "", + "help_info": { + "links": [ + {} + ] + }, + "localized_message_info": { + "locale": "", + "message": "" + }, + "request_info": { + "request_id": "", + "serving_data": "" + }, + "resource_info": { + "description": "", + "owner": "", + "required_permissions": [ + "" + ], + "resource_name": "", + "user": "" + }, + "tool_error_info": { + "execution_id": "", + "tool_error_code": "", + "tool_error_message": "" + }, + "validation_error_info": { + "field_violations": [ + {} + ] + } +} +``` + +##### Status: 500 Internal server error — an unexpected error occurred while processing the invitation resend request. This may be due to database connectivity issues, problems generating the secure magic link, email delivery service failures, or transaction errors during invitation processing. Contact support if the problem persists. + +###### Content-Type: application/json + +- **`debug_info`** + + `object` — Describes additional debugging info. + + - **`detail`** + + `string` — Additional debugging information provided by the server. + + - **`stack_entries`** + + `array` — The stack trace entries indicating where the error occurred. + + **Items:** + + `string` + +- **`error_code`** + + `string` + +- **`help_info`** + + `object` — HelpInfo provides documentation links attached to an error response. When present in ErrorInfo, clients should surface these links to help developers resolve the error. For example, a missing required field error may include a link to the relevant guide. + + - **`links`** + + `array` — One or more links relevant to resolving the error. + + **Items:** + + - **`description`** + + `string` — Human-readable label for the link (e.g. "User verification flow"). + + - **`url`** + + `string` — Absolute URL to the documentation page (e.g. "https\://docs.scalekit.com/..."). + +- **`localized_message_info`** + + `object` + + - **`locale`** + + `string` + + - **`message`** + + `string` + +- **`request_info`** + + `object` — Contains metadata about the request that clients can attach when filing a bug or providing other forms of feedback. + + - **`request_id`** + + `string` — An opaque string that should only be interpreted by the service generating it. For example, it can be used to identify requests in the service's logs. + + - **`serving_data`** + + `string` — Any data that was used to serve this request. For example, an encrypted stack trace that can be sent back to the service provider for debugging. + +- **`resource_info`** + + `object` — Describes the resource that is being accessed. + + - **`description`** + + `string` — Describes what error is encountered when accessing this resource. For example, updating a cloud project may require the \`writer\` permission on the developer console project. + + - **`owner`** + + `string` + + - **`required_permissions`** + + `array` — The required permissions needed to access the resource. + + **Items:** + + `string` + + - **`resource_name`** + + `string` + + - **`user`** + + `string` + +- **`tool_error_info`** + + `object` + + - **`execution_id`** + + `string` + + - **`tool_error_code`** + + `string` + + - **`tool_error_message`** + + `string` + +- **`validation_error_info`** + + `object` — Describes violations in a client request. This error type focuses on the syntactic aspects of the request. + + - **`field_violations`** + + `array` — Describes all violations in a client request. + + **Items:** + + - **`constraint`** + + `string` + + - **`description`** + + `string` — A description of why the request element is bad. + + - **`field`** + + `string` + +**Example:** + +```json +{ + "debug_info": { + "detail": "", + "stack_entries": [ + "" + ] + }, + "error_code": "", + "help_info": { + "links": [ + {} + ] + }, + "localized_message_info": { + "locale": "", + "message": "" + }, + "request_info": { + "request_id": "", + "serving_data": "" + }, + "resource_info": { + "description": "", + "owner": "", + "required_permissions": [ + "" + ], + "resource_name": "", + "user": "" + }, + "tool_error_info": { + "execution_id": "", + "tool_error_code": "", + "tool_error_message": "" + }, + "validation_error_info": { + "field_violations": [ + {} + ] + } +} +``` + +### Add existing user to organization + +- **Method:** `POST` +- **Path:** `/api/v1/memberships/organizations/{organization_id}/users/{id}` +- **Tags:** Users + +Adds an existing user to an organization and assigns them specific roles and permissions. Use this endpoint when you want to grant an existing user access to a particular organization. You can specify roles, metadata, and other membership details during the invitation process. + +#### Request Body + +##### Content-Type: application/json + +- **`inviter_email`** + + `string` — Email address of the user who invited this member. Must be a valid email address. + +- **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + +- **`roles`** + + `array` — Role to assign to the user within the organization + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + +**Example:** + +```json +{ + "inviter_email": "john.doe@example.com", + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "roles": [ + { + "name": "admin" + } + ] +} +``` + +#### Responses + +##### Status: 201 User successfully added to the organization. Returns details of the updated membership details + +###### Content-Type: application/json + +- **`user`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "user": { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } +} +``` + +### Delete organization membership for user + +- **Method:** `DELETE` +- **Path:** `/api/v1/memberships/organizations/{organization_id}/users/{id}` +- **Tags:** Users + +Removes a user from an organization by user ID or external ID. If the user has no memberships left and cascade is true, the user is also deleted. This action is irreversible and may also remove related group memberships. + +#### Responses + +##### Status: 200 User successfully marked for deletion. No content returned + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Update organization membership for user + +- **Method:** `PATCH` +- **Path:** `/api/v1/memberships/organizations/{organization_id}/users/{id}` +- **Tags:** Users + +Updates a user's membership details within an organization by user ID or external ID. You can update roles and membership metadata. + +#### Request Body + +##### Content-Type: application/json + +- **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + +- **`roles`** + + `array` — Role to assign to the user within the organization + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + +**Example:** + +```json +{ + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "roles": [ + { + "name": "admin" + } + ] +} +``` + +#### Responses + +##### Status: 200 Membership updated successfully. Returns the updated user object. + +###### Content-Type: application/json + +- **`user`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "user": { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } +} +``` + +### List organizations + +- **Method:** `GET` +- **Path:** `/api/v1/organizations` +- **Tags:** Organizations + +Retrieve a paginated list of organizations within your environment. The response includes a `page_token` that can be used to access subsequent pages of results. + +#### Responses + +##### Status: 200 Successfully retrieved the list of organizations + +###### Content-Type: application/json + +- **`next_page_token`** + + `string` — Pagination token for the next page of results. Use this token to fetch the next page. + +- **`organizations`** + + `array` — List of organization objects + + **Items:** + + - **`create_time` (required)** + + `string`, format: `date-time` — Timestamp when the organization was created + + - **`display_name`** + + `string` — Name of the organization. Must be between 1 and 200 characters + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique scalekit-generated identifier that uniquely references an organization + + - **`metadata`** + + `object` — Key value pairs extension attributes. + + - **`region_code`** + + `string`, possible values: `"US", "EU"` — Geographic region code for the organization. Currently limited to US. + + - **`settings`** + + `object` — Configuration options that control organization-level features and capabilities + + - **`features`** + + `array` — List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization + + **Items:** + + - **`enabled` (required)** + + `boolean` — Whether the feature is enabled (true) or disabled (false) for this organization + + - **`name` (required)** + + `string` — Feature identifier. Supported values include: "sso" (Single Sign-On), "directory\_sync" (Directory Synchronization), "domain\_verification" (Domain Verification) + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the organization was last updated + +- **`prev_page_token`** + + `string` — Pagination token for the previous page of results. Use this token to fetch the previous page. + +- **`total_size`** + + `integer`, format: `int64` — Total number of organizations in the environment. + +**Example:** + +```json +{ + "next_page_token": "", + "organizations": [ + { + "create_time": "2025-02-15T06:23:44.560000Z", + "display_name": "Megasoft", + "external_id": "my_unique_id", + "id": "org_59615193906282635", + "metadata": { + "additionalProperty": "" + }, + "region_code": "US", + "settings": null, + "update_time": "2025-02-15T06:23:44.560000Z" + } + ], + "prev_page_token": "", + "total_size": 30 +} +``` + +##### Status: 400 Invalid page token + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Create an organization + +- **Method:** `POST` +- **Path:** `/api/v1/organizations` +- **Tags:** Organizations + +Creates a new organization in your environment. Use this endpoint to add a new tenant that can be configured with various settings and metadata + +#### Request Body + +##### Content-Type: application/json + +- **`display_name` (required)** + + `string` — Name of the organization. Must be between 1 and 200 characters. + +- **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + +- **`metadata`** + + `object` + +**Example:** + +```json +{ + "display_name": "Megasoft Inc", + "external_id": "my_unique_id", + "metadata": { + "additionalProperty": "" + } +} +``` + +#### Responses + +##### Status: 201 Returns the newly created organization with its unique identifier and settings + +###### Content-Type: application/json + +- **`organization`** + + `object` — The newly created organization containing its ID, settings, and metadata + + - **`create_time` (required)** + + `string`, format: `date-time` — Timestamp when the organization was created + + - **`display_name`** + + `string` — Name of the organization. Must be between 1 and 200 characters + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique scalekit-generated identifier that uniquely references an organization + + - **`metadata`** + + `object` — Key value pairs extension attributes. + + - **`region_code`** + + `string`, possible values: `"US", "EU"` — Geographic region code for the organization. Currently limited to US. + + - **`settings`** + + `object` — Configuration options that control organization-level features and capabilities + + - **`features`** + + `array` — List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization + + **Items:** + + - **`enabled` (required)** + + `boolean` — Whether the feature is enabled (true) or disabled (false) for this organization + + - **`name` (required)** + + `string` — Feature identifier. Supported values include: "sso" (Single Sign-On), "directory\_sync" (Directory Synchronization), "domain\_verification" (Domain Verification) + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the organization was last updated + +**Example:** + +```json +{ + "organization": { + "create_time": "2025-02-15T06:23:44.560000Z", + "display_name": "Megasoft", + "external_id": "my_unique_id", + "id": "org_59615193906282635", + "metadata": { + "additionalProperty": "" + }, + "region_code": "US", + "settings": null, + "update_time": "2025-02-15T06:23:44.560000Z" + } +} +``` + +### Get organization details + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{id}` +- **Tags:** Organizations + +Retrieves organization details by Scalekit ID, including name, region, metadata, and settings + +#### Responses + +##### Status: 200 Returns the complete organization object with ID, display name, settings, and metadata + +###### Content-Type: application/json + +- **`organization`** + + `object` — The newly created organization + + - **`create_time` (required)** + + `string`, format: `date-time` — Timestamp when the organization was created + + - **`display_name`** + + `string` — Name of the organization. Must be between 1 and 200 characters + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique scalekit-generated identifier that uniquely references an organization + + - **`metadata`** + + `object` — Key value pairs extension attributes. + + - **`region_code`** + + `string`, possible values: `"US", "EU"` — Geographic region code for the organization. Currently limited to US. + + - **`settings`** + + `object` — Configuration options that control organization-level features and capabilities + + - **`features`** + + `array` — List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization + + **Items:** + + - **`enabled` (required)** + + `boolean` — Whether the feature is enabled (true) or disabled (false) for this organization + + - **`name` (required)** + + `string` — Feature identifier. Supported values include: "sso" (Single Sign-On), "directory\_sync" (Directory Synchronization), "domain\_verification" (Domain Verification) + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the organization was last updated + +**Example:** + +```json +{ + "organization": { + "create_time": "2025-02-15T06:23:44.560000Z", + "display_name": "Megasoft", + "external_id": "my_unique_id", + "id": "org_59615193906282635", + "metadata": { + "additionalProperty": "" + }, + "region_code": "US", + "settings": null, + "update_time": "2025-02-15T06:23:44.560000Z" + } +} +``` + +### Delete an organization + +- **Method:** `DELETE` +- **Path:** `/api/v1/organizations/{id}` +- **Tags:** Organizations + +Remove an existing organization from the environment using its unique identifier + +#### Responses + +##### Status: 200 Organization successfully deleted and no longer accessible + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Update organization details + +- **Method:** `PATCH` +- **Path:** `/api/v1/organizations/{id}` +- **Tags:** Organizations + +Updates an organization's display name, external ID, or metadata. Requires a valid organization identifier. Region code cannot be modified through this endpoint. + +#### Request Body + +##### Content-Type: application/json + +- **`display_name`** + + `string` — Name of the organization to display in the UI. Must be between 1 and 200 characters + +- **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system + +- **`metadata`** + + `object` — Custom key-value pairs to store with the organization. Keys must be 3-25 characters, values must be 1-256 characters. Maximum 10 pairs allowed. + +**Example:** + +```json +{ + "display_name": "Acme Corporation", + "external_id": "tenant_12345", + "metadata": { + "industry": "technology" + } +} +``` + +#### Responses + +##### Status: 200 Returns the updated organization with all current details reflected in the response. + +###### Content-Type: application/json + +- **`organization`** + + `object` — Updated organization details + + - **`create_time` (required)** + + `string`, format: `date-time` — Timestamp when the organization was created + + - **`display_name`** + + `string` — Name of the organization. Must be between 1 and 200 characters + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique scalekit-generated identifier that uniquely references an organization + + - **`metadata`** + + `object` — Key value pairs extension attributes. + + - **`region_code`** + + `string`, possible values: `"US", "EU"` — Geographic region code for the organization. Currently limited to US. + + - **`settings`** + + `object` — Configuration options that control organization-level features and capabilities + + - **`features`** + + `array` — List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization + + **Items:** + + - **`enabled` (required)** + + `boolean` — Whether the feature is enabled (true) or disabled (false) for this organization + + - **`name` (required)** + + `string` — Feature identifier. Supported values include: "sso" (Single Sign-On), "directory\_sync" (Directory Synchronization), "domain\_verification" (Domain Verification) + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the organization was last updated + +**Example:** + +```json +{ + "organization": { + "create_time": "2025-02-15T06:23:44.560000Z", + "display_name": "Megasoft", + "external_id": "my_unique_id", + "id": "org_59615193906282635", + "metadata": { + "additionalProperty": "" + }, + "region_code": "US", + "settings": null, + "update_time": "2025-02-15T06:23:44.560000Z" + } +} +``` + +### Generate admin portal link + +- **Method:** `PUT` +- **Path:** `/api/v1/organizations/{id}/portal_links` +- **Tags:** Organizations + +Creates a single use Admin Portal URL valid for 1 minute. Once the generated admin portal URL is accessed or rendered, a temporary session of 6 hours is created to allow the admin to update SSO/SCIM configuration. + +#### Responses + +##### Status: 200 Admin Portal link generated successfully. Returns the portal URL and expiration timestamp. + +###### Content-Type: application/json + +- **`link`** + + `object` — Contains the generated admin portal link details. The link URL can be shared with organization administrators to set up: Single Sign-On (SSO) authentication and directory synchronization + + - **`expire_time`** + + `string`, format: `date-time` — Expiry time of the link. The link is valid for 1 minute. + + - **`id`** + + `string` — Unique Identifier for the link + + - **`location`** + + `string` — Location of the link. This is the URL that can be used to access the Admin portal. The link is valid for 1 minute + +**Example:** + +```json +{ + "link": { + "expire_time": "2024-02-06T14:48:00Z", + "id": "lnk_123123123123123", + "location": "https://scalekit.com/portal/lnk_123123123123123" + } +} +``` + +### Toggle organization settings + +- **Method:** `PATCH` +- **Path:** `/api/v1/organizations/{id}/settings` +- **Tags:** Organizations + +Updates configuration settings for an organization. Supports modifying SSO configuration, directory synchronization settings, and session parameters. Requires organization ID and the specific settings to update. + +#### Request Body + +##### Content-Type: application/json + +- **`features`** + + `array` — List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization + + **Items:** + + - **`enabled` (required)** + + `boolean` — Whether the feature is enabled (true) or disabled (false) for this organization + + - **`name` (required)** + + `string` — Feature identifier. Supported values include: "sso" (Single Sign-On), "directory\_sync" (Directory Synchronization), "domain\_verification" (Domain Verification) + +**Example:** + +```json +{ + "features": [ + { + "enabled": true, + "name": "sso" + }, + { + "enabled": false, + "name": "directory_sync" + } + ] +} +``` + +#### Responses + +##### Status: 200 Returns the complete organization object with updated settings applied. Contains all organization details including ID, display name, and the modified settings. + +###### Content-Type: application/json + +- **`organization`** + + `object` — The newly created organization + + - **`create_time` (required)** + + `string`, format: `date-time` — Timestamp when the organization was created + + - **`display_name`** + + `string` — Name of the organization. Must be between 1 and 200 characters + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique scalekit-generated identifier that uniquely references an organization + + - **`metadata`** + + `object` — Key value pairs extension attributes. + + - **`region_code`** + + `string`, possible values: `"US", "EU"` — Geographic region code for the organization. Currently limited to US. + + - **`settings`** + + `object` — Configuration options that control organization-level features and capabilities + + - **`features`** + + `array` — List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization + + **Items:** + + - **`enabled` (required)** + + `boolean` — Whether the feature is enabled (true) or disabled (false) for this organization + + - **`name` (required)** + + `string` — Feature identifier. Supported values include: "sso" (Single Sign-On), "directory\_sync" (Directory Synchronization), "domain\_verification" (Domain Verification) + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the organization was last updated + +**Example:** + +```json +{ + "organization": { + "create_time": "2025-02-15T06:23:44.560000Z", + "display_name": "Megasoft", + "external_id": "my_unique_id", + "id": "org_59615193906282635", + "metadata": { + "additionalProperty": "" + }, + "region_code": "US", + "settings": null, + "update_time": "2025-02-15T06:23:44.560000Z" + } +} +``` + +##### Status: 400 Invalid request - occurs when the settings payload contains invalid values or unsupported configuration + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 404 Organization not found - the specified organization ID doesn't exist + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### List organization roles + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{org_id}/roles` +- **Tags:** Roles + +Retrieves all environment roles and organization specific roles. Use this endpoint to view all role definitions, including custom roles and their configurations. You can optionally include permission details for each role to understand their capabilities. This is useful for role management, auditing organization access controls, or understanding the available access levels within the organization. + +#### Responses + +##### Status: 200 Successfully retrieved list of organization roles. Returns all roles with their metadata and optionally their permissions. + +###### Content-Type: application/json + +- **`roles`** + + `array` — List of roles objects + + **Items:** + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "roles": [ + { + "default_creator": true, + "default_member": true, + "dependent_roles_count": 3, + "description": "Can create, edit, and publish content but cannot delete or manage users", + "display_name": "Content Editor", + "extends": "admin_role", + "id": "role_1234abcd5678efgh", + "is_org_role": true, + "name": "content_editor", + "permissions": [ + { + "description": "Read Content", + "name": "read:content", + "role_name": "admin_role" + }, + { + "description": "Write Content", + "name": "write:content", + "role_name": "editor_role" + } + ] + } + ] +} +``` + +### Create organization role + +- **Method:** `POST` +- **Path:** `/api/v1/organizations/{org_id}/roles` +- **Tags:** Roles + +Creates a new role within the specified organization with basic configuration including name, display name, description, and permissions. Use this endpoint to define custom roles that can be assigned to users within the organization. You can create hierarchical roles by extending existing roles and assign specific permissions to control access levels. The role will be scoped to the organization and can be used for organization-specific access control. + +#### Request Body + +##### Content-Type: application/json + +- **`description`** + + `string` — Description of the organization's role + +- **`display_name`** + + `string` — Display name of the organization's role + +- **`extends`** + + `string` — Base role name for hierarchical roles + +- **`name`** + + `string` — Unique name of the organization's role + +- **`permissions`** + + `array` — List of permission names to assign to this role. Permissions must exist in the current environment. + + **Items:** + + `string` + +**Example:** + +```json +{ + "description": "Organization Viewer Role will be used only for viewing the objects", + "display_name": "Organization Viewer Role", + "extends": "admin_role", + "name": "org_viewer_role", + "permissions": [ + "read:users", + "write:documents" + ] +} +``` + +#### Responses + +##### Status: 201 Organization role created successfully. Returns the complete role object with system-generated ID and timestamps. + +###### Content-Type: application/json + +- **`role`** + + `object` + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "role": { + "default_creator": true, + "default_member": true, + "dependent_roles_count": 3, + "description": "Can create, edit, and publish content but cannot delete or manage users", + "display_name": "Content Editor", + "extends": "admin_role", + "id": "role_1234abcd5678efgh", + "is_org_role": true, + "name": "content_editor", + "permissions": [ + { + "description": "Read Content", + "name": "read:content", + "role_name": "admin_role" + }, + { + "description": "Write Content", + "name": "write:content", + "role_name": "editor_role" + } + ] + } +} +``` + +### Get organization role details + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{org_id}/roles/{role_name}` +- **Tags:** Roles + +Retrieves complete information for a specific organization role including metadata, inheritance details, and optionally permissions. Use this endpoint to audit role configuration and understand the role's place in the organization's role hierarchy. You can include permission details to see what capabilities the role provides. This operation is useful for role management, user assignment decisions, or understanding organization access controls. + +#### Responses + +##### Status: 200 Successfully retrieved organization role details. Returns the role object including metadata and inheritance details. Permissions are included only when requested via the include parameter. + +###### Content-Type: application/json + +- **`role`** + + `object` + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "role": { + "default_creator": true, + "default_member": true, + "dependent_roles_count": 3, + "description": "Can create, edit, and publish content but cannot delete or manage users", + "display_name": "Content Editor", + "extends": "admin_role", + "id": "role_1234abcd5678efgh", + "is_org_role": true, + "name": "content_editor", + "permissions": [ + { + "description": "Read Content", + "name": "read:content", + "role_name": "admin_role" + }, + { + "description": "Write Content", + "name": "write:content", + "role_name": "editor_role" + } + ] + } +} +``` + +### Update organization role + +- **Method:** `PUT` +- **Path:** `/api/v1/organizations/{org_id}/roles/{role_name}` +- **Tags:** Roles + +Modifies an existing organization role's properties including display name, description, permissions, and inheritance settings. Use this endpoint to update role metadata, change permission assignments, or modify role hierarchy within the organization. Only the fields you specify will be updated, leaving other properties unchanged. When updating permissions, the new list replaces all existing permissions for the role. + +#### Request Body + +##### Content-Type: application/json + +- **`description`** + + `string` — Detailed description of the role's purpose, capabilities, and intended use cases. Maximum 2000 characters. + +- **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces, reports, and user-facing communications. + +- **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance where this role inherits all permissions from the base role. + +- **`permissions`** + + `array` — List of permission names to assign to this role. When provided, this replaces all existing role-permission mappings. Permissions must exist in the current environment. Maximum 100 permissions per role. + + **Items:** + + `string` + +**Example:** + +```json +{ + "description": "Can create, edit, publish, and approve content. Cannot delete content or manage user accounts.", + "display_name": "Senior Content Editor", + "extends": "content_editor", + "permissions": [ + "read:content", + "write:content", + "publish:content", + "approve:content" + ] +} +``` + +#### Responses + +##### Status: 200 Organization role updated successfully. Returns the modified role object with updated timestamps. + +###### Content-Type: application/json + +- **`role`** + + `object` + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "role": { + "default_creator": true, + "default_member": true, + "dependent_roles_count": 3, + "description": "Can create, edit, and publish content but cannot delete or manage users", + "display_name": "Content Editor", + "extends": "admin_role", + "id": "role_1234abcd5678efgh", + "is_org_role": true, + "name": "content_editor", + "permissions": [ + { + "description": "Read Content", + "name": "read:content", + "role_name": "admin_role" + }, + { + "description": "Write Content", + "name": "write:content", + "role_name": "editor_role" + } + ] + } +} +``` + +### Delete organization role + +- **Method:** `DELETE` +- **Path:** `/api/v1/organizations/{org_id}/roles/{role_name}` +- **Tags:** Roles + +Permanently removes a role from the organization and optionally reassigns users who had that role to a different role. Use this endpoint when you need to clean up unused roles or restructure your organization's access control system. If users are assigned to the role being deleted, you can provide a reassign\_role\_name to move those users to a different role before deletion. This action cannot be undone, so ensure no critical users depend on the role before deletion. + +#### Responses + +##### Status: 200 Organization role successfully deleted and users reassigned if specified. No content returned. + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Set default organization roles + +- **Method:** `PATCH` +- **Path:** `/api/v1/organizations/{org_id}/roles:set_defaults` +- **Tags:** Roles + +Updates the default member role for the specified organization. Use this endpoint to configure which role is automatically assigned to new users when they join the organization. The system will validate that the specified role exists and update the organization settings accordingly. This configuration affects all new user invitations and memberships within the organization. + +#### Request Body + +##### Content-Type: application/json + +- **`default_member_role`** + + `string` — Unique name of the default member role + +**Example:** + +```json +{ + "default_member_role": "member" +} +``` + +#### Responses + +##### Status: 200 Default organization roles updated successfully. Returns the updated default member role object with complete role information. + +###### Content-Type: application/json + +- **`default_member`** + + `object` — Updated default member role + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "default_member": { + "description": "Role for regular members", + "display_name": "Member Role", + "id": "role_0987654321", + "name": "member" + } +} +``` + +### List organization API clients + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{organization_id}/clients` +- **Tags:** API Auth + +Retrieves a paginated list of API clients for a specific organization. Returns client details including metadata, scopes, and secret information (without exposing actual secret values). + +#### Responses + +##### Status: 200 List of organization API clients returned successfully. Each client includes its configuration details and metadata. + +###### Content-Type: application/json + +- **`clients`** + + `array` — List of API client objects for the organization. Each client includes its configuration, metadata, and active secrets (without exposing actual secret values). + + **Items:** + + - **`audience`** + + `array` — The intended recipients of access tokens issued to this client. Each audience value should be a URI that identifies an API or service. + + **Items:** + + `string` + + - **`client_id`** + + `string` — The unique identifier for this API client. This ID is used to identify the client in API requests and logs. It is automatically generated when the client is created and cannot be modified. + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this API client was created. This field is automatically set by the server and cannot be modified. + + - **`custom_claims`** + + `array` — Additional claims included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. + + **Items:** + + - **`key`** + + `string` — The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose. + + - **`value`** + + `string` — The value of the custom claim. This value will be included in access tokens issued to the client. + + - **`description`** + + `string` — A detailed description of the client's purpose and usage. This helps administrators understand what the client is used for. + + - **`expiry`** + + `string`, format: `int64` — Expiry time in seconds for the token generated by the client + + - **`is_cimd`** + + `boolean` — Indicates if the client was created via Client ID Metadata Document (CIMD). CIMD clients can update their own configuration according to the CIMD specification. + + - **`is_dcr`** + + `boolean` — Indicates if the client was created via Dynamic Client Registration (DCR). Clients created through DCR may have different management and lifecycle policies compared to those created manually. + + - **`metadata_uri`** + + `string` — The URI to the client's metadata, which is utilized to obtain the client's configuration details + + - **`name`** + + `string` — The display name of the API client. This name helps identify the client in the dashboard and logs. + + - **`organization_id`** + + `string` — The ID of the organization that owns this API client. This ID is used to associate the client with the correct organization and enforce organization-specific access controls. + + - **`redirect_uris`** + + `array` — The redirect URI for this API client. This URI is used in the OAuth 2.0 authorization flow to redirect users after authentication. + + **Items:** + + `string` + + - **`resource_id`** + + `string` — The ID of the resource associated with this M2M client. This field is used to link the client to a specific resource in the system. + + - **`scopes`** + + `array` — The OAuth 2.0 scopes granted to this client. These scopes determine what resources and actions the client can access. + + **Items:** + + `string` + + - **`secrets`** + + `array` — List of client secrets associated with this client. Each secret can be used for authentication, but only the most recently created secret is typically active. Secrets are stored securely and their values are never returned after creation. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this secret was created. This field is automatically set by the server and cannot be modified. + + - **`created_by`** + + `string` — The identifier of the user or system that created this secret. This field helps track who created the secret for audit and compliance purposes. + + - **`expire_time`** + + `string`, format: `date-time` — The timestamp when this secret will expire. After this time, the secret cannot be used for authentication regardless of its status. If not set, the secret does not expire. + + - **`id`** + + `string` — The unique identifier for this client secret. This ID is used to reference the secret in API requests for management operations like updating or deleting the secret. + + - **`last_used_time`** + + `string`, format: `date-time` — The timestamp when this secret was last used for authentication. This field helps track secret usage for security monitoring and identifying unused secrets that may be candidates for rotation. + + - **`plain_secret`** + + `string` — The full plaintext secret value. This field is only populated when the secret is first created and is never stored by the server. It must be securely stored by the client application as it cannot be retrieved again. + + - **`secret_suffix`** + + `string` — A suffix that helps identify this secret. This is the last few characters of the full secret value but is not sufficient for authentication. Helps identify which secret is being used in logs and debugging. + + - **`status`** + + `string`, possible values: `"INACTIVE"` — The current status of this secret. A secret must be ACTIVE to be used for authentication. INACTIVE secrets cannot be used for authentication but are retained for audit purposes. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this secret was last updated. This field is automatically updated by the server when the secret's status changes or other properties are modified. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this API client was last updated. This field is automatically updated by the server whenever the client's configuration changes. + +- **`next_page_token`** + + `string` — Pagination token for the next page of results. Use this token to fetch the next page. + +- **`prev_page_token`** + + `string` — Pagination token for the previous page of results. Use this token to fetch the previous page. + +- **`total_size`** + + `integer`, format: `int64` — Total number of API clients in the organization. + +**Example:** + +```json +{ + "clients": [ + { + "audience": [ + "https://api.example.com" + ], + "client_id": "m2morg_1231234233424344", + "create_time": "2024-01-05T14:48:00Z", + "custom_claims": [ + {} + ], + "description": "Service account for automated deployment processes", + "expiry": 3600, + "is_cimd": false, + "is_dcr": false, + "metadata_uri": "https://example.com/client-metadata.json", + "name": "GitHub Actions Deployment Service", + "organization_id": "org_1231234233424344", + "redirect_uris": [ + "https://example.com/callback" + ], + "resource_id": "app_1231234233424344", + "scopes": [ + "deploy:resources", + "read:deployments" + ], + "secrets": [ + {} + ], + "update_time": "2024-01-05T14:48:00Z" + } + ], + "next_page_token": "", + "prev_page_token": "", + "total_size": 30 +} +``` + +### Create organization API client + +- **Method:** `POST` +- **Path:** `/api/v1/organizations/{organization_id}/clients` +- **Tags:** API Auth + +Creates a new API client for an organization. Returns the client details and a plain secret (available only once). + +#### Request Body + +##### Content-Type: application/json + +- **`audience`** + + `array` — The intended recipients of the access tokens issued to this client. Each audience value should be a URI that identifies the API or service that will validate the token. + + **Items:** + + `string` + +- **`custom_claims`** + + `array` — Additional claims to be included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. Keep claims minimal to avoid increasing token size. + + **Items:** + + - **`key`** + + `string` — The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose. + + - **`value`** + + `string` — The value of the custom claim. This value will be included in access tokens issued to the client. + +- **`description`** + + `string` — A detailed explanation of the client's purpose and usage. This helps administrators understand what the client is used for and who manages it. + +- **`expiry`** + + `string`, format: `int64` — Expiry time in seconds for the token generated by the client + +- **`name`** + + `string` — A descriptive name for the API client that helps identify its purpose. This name is displayed in the dashboard and logs. Must be between 1 and 128 characters. + +- **`scopes`** + + `array` — OAuth 2.0 scopes that define the permissions granted to this client. Each scope represents a specific permission or set of permissions. The client can only access resources that match its granted scopes. + + **Items:** + + `string` + +**Example:** + +```json +{ + "audience": [ + "https://api.example.com/api/analytics", + "https://deployment-api.acmecorp.com" + ], + "custom_claims": [ + { + "key": "environment", + "value": "production" + }, + { + "key": "service", + "value": "deployment" + } + ], + "description": "Service account for GitHub Actions to deploy resources to production", + "expiry": 3600, + "name": "GitHub Actions Deployment Service", + "scopes": [ + "deploy:resources", + "read:deployments" + ] +} +``` + +#### Responses + +##### Status: 201 API client created successfully. Returns the client ID and plain secret (only available at creation time). The client can be configured with scopes, audience values, and custom claims for fine-grained access control. + +###### Content-Type: application/json + +- **`client`** + + `object` — Details of the created client + + - **`audience`** + + `array` — The intended recipients of access tokens issued to this client. Each audience value should be a URI that identifies an API or service. + + **Items:** + + `string` + + - **`client_id`** + + `string` — The unique identifier for this API client. This ID is used to identify the client in API requests and logs. It is automatically generated when the client is created and cannot be modified. + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this API client was created. This field is automatically set by the server and cannot be modified. + + - **`custom_claims`** + + `array` — Additional claims included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. + + **Items:** + + - **`key`** + + `string` — The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose. + + - **`value`** + + `string` — The value of the custom claim. This value will be included in access tokens issued to the client. + + - **`description`** + + `string` — A detailed description of the client's purpose and usage. This helps administrators understand what the client is used for. + + - **`expiry`** + + `string`, format: `int64` — Expiry time in seconds for the token generated by the client + + - **`is_cimd`** + + `boolean` — Indicates if the client was created via Client ID Metadata Document (CIMD). CIMD clients can update their own configuration according to the CIMD specification. + + - **`is_dcr`** + + `boolean` — Indicates if the client was created via Dynamic Client Registration (DCR). Clients created through DCR may have different management and lifecycle policies compared to those created manually. + + - **`metadata_uri`** + + `string` — The URI to the client's metadata, which is utilized to obtain the client's configuration details + + - **`name`** + + `string` — The display name of the API client. This name helps identify the client in the dashboard and logs. + + - **`organization_id`** + + `string` — The ID of the organization that owns this API client. This ID is used to associate the client with the correct organization and enforce organization-specific access controls. + + - **`redirect_uris`** + + `array` — The redirect URI for this API client. This URI is used in the OAuth 2.0 authorization flow to redirect users after authentication. + + **Items:** + + `string` + + - **`resource_id`** + + `string` — The ID of the resource associated with this M2M client. This field is used to link the client to a specific resource in the system. + + - **`scopes`** + + `array` — The OAuth 2.0 scopes granted to this client. These scopes determine what resources and actions the client can access. + + **Items:** + + `string` + + - **`secrets`** + + `array` — List of client secrets associated with this client. Each secret can be used for authentication, but only the most recently created secret is typically active. Secrets are stored securely and their values are never returned after creation. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this secret was created. This field is automatically set by the server and cannot be modified. + + - **`created_by`** + + `string` — The identifier of the user or system that created this secret. This field helps track who created the secret for audit and compliance purposes. + + - **`expire_time`** + + `string`, format: `date-time` — The timestamp when this secret will expire. After this time, the secret cannot be used for authentication regardless of its status. If not set, the secret does not expire. + + - **`id`** + + `string` — The unique identifier for this client secret. This ID is used to reference the secret in API requests for management operations like updating or deleting the secret. + + - **`last_used_time`** + + `string`, format: `date-time` — The timestamp when this secret was last used for authentication. This field helps track secret usage for security monitoring and identifying unused secrets that may be candidates for rotation. + + - **`plain_secret`** + + `string` — The full plaintext secret value. This field is only populated when the secret is first created and is never stored by the server. It must be securely stored by the client application as it cannot be retrieved again. + + - **`secret_suffix`** + + `string` — A suffix that helps identify this secret. This is the last few characters of the full secret value but is not sufficient for authentication. Helps identify which secret is being used in logs and debugging. + + - **`status`** + + `string`, possible values: `"INACTIVE"` — The current status of this secret. A secret must be ACTIVE to be used for authentication. INACTIVE secrets cannot be used for authentication but are retained for audit purposes. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this secret was last updated. This field is automatically updated by the server when the secret's status changes or other properties are modified. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this API client was last updated. This field is automatically updated by the server whenever the client's configuration changes. + +- **`plain_secret`** + + `string` — Client secret value (only returned once at creation) + +**Example:** + +```json +{ + "client": { + "audience": [ + "https://api.example.com" + ], + "client_id": "m2morg_1231234233424344", + "create_time": "2024-01-05T14:48:00Z", + "custom_claims": [ + {} + ], + "description": "Service account for automated deployment processes", + "expiry": 3600, + "is_cimd": false, + "is_dcr": false, + "metadata_uri": "https://example.com/client-metadata.json", + "name": "GitHub Actions Deployment Service", + "organization_id": "org_1231234233424344", + "redirect_uris": [ + "https://example.com/callback" + ], + "resource_id": "app_1231234233424344", + "scopes": [ + "deploy:resources", + "read:deployments" + ], + "secrets": [ + {} + ], + "update_time": "2024-01-05T14:48:00Z" + }, + "plain_secret": "CdExsdErfccxDDssddfffgfeFHH1" +} +``` + +### Get organization API client + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{organization_id}/clients/{client_id}` +- **Tags:** API Auth + +Retrieves details of a specific API client in an organization. + +#### Responses + +##### Status: 200 Returns the complete API client configuration, including all current settings and a list of active secrets. Note that secret values are not included in the response for security reasons. + +###### Content-Type: application/json + +- **`client`** + + `object` — Details of the requested client + + - **`audience`** + + `array` — The intended recipients of access tokens issued to this client. Each audience value should be a URI that identifies an API or service. + + **Items:** + + `string` + + - **`client_id`** + + `string` — The unique identifier for this API client. This ID is used to identify the client in API requests and logs. It is automatically generated when the client is created and cannot be modified. + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this API client was created. This field is automatically set by the server and cannot be modified. + + - **`custom_claims`** + + `array` — Additional claims included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. + + **Items:** + + - **`key`** + + `string` — The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose. + + - **`value`** + + `string` — The value of the custom claim. This value will be included in access tokens issued to the client. + + - **`description`** + + `string` — A detailed description of the client's purpose and usage. This helps administrators understand what the client is used for. + + - **`expiry`** + + `string`, format: `int64` — Expiry time in seconds for the token generated by the client + + - **`is_cimd`** + + `boolean` — Indicates if the client was created via Client ID Metadata Document (CIMD). CIMD clients can update their own configuration according to the CIMD specification. + + - **`is_dcr`** + + `boolean` — Indicates if the client was created via Dynamic Client Registration (DCR). Clients created through DCR may have different management and lifecycle policies compared to those created manually. + + - **`metadata_uri`** + + `string` — The URI to the client's metadata, which is utilized to obtain the client's configuration details + + - **`name`** + + `string` — The display name of the API client. This name helps identify the client in the dashboard and logs. + + - **`organization_id`** + + `string` — The ID of the organization that owns this API client. This ID is used to associate the client with the correct organization and enforce organization-specific access controls. + + - **`redirect_uris`** + + `array` — The redirect URI for this API client. This URI is used in the OAuth 2.0 authorization flow to redirect users after authentication. + + **Items:** + + `string` + + - **`resource_id`** + + `string` — The ID of the resource associated with this M2M client. This field is used to link the client to a specific resource in the system. + + - **`scopes`** + + `array` — The OAuth 2.0 scopes granted to this client. These scopes determine what resources and actions the client can access. + + **Items:** + + `string` + + - **`secrets`** + + `array` — List of client secrets associated with this client. Each secret can be used for authentication, but only the most recently created secret is typically active. Secrets are stored securely and their values are never returned after creation. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this secret was created. This field is automatically set by the server and cannot be modified. + + - **`created_by`** + + `string` — The identifier of the user or system that created this secret. This field helps track who created the secret for audit and compliance purposes. + + - **`expire_time`** + + `string`, format: `date-time` — The timestamp when this secret will expire. After this time, the secret cannot be used for authentication regardless of its status. If not set, the secret does not expire. + + - **`id`** + + `string` — The unique identifier for this client secret. This ID is used to reference the secret in API requests for management operations like updating or deleting the secret. + + - **`last_used_time`** + + `string`, format: `date-time` — The timestamp when this secret was last used for authentication. This field helps track secret usage for security monitoring and identifying unused secrets that may be candidates for rotation. + + - **`plain_secret`** + + `string` — The full plaintext secret value. This field is only populated when the secret is first created and is never stored by the server. It must be securely stored by the client application as it cannot be retrieved again. + + - **`secret_suffix`** + + `string` — A suffix that helps identify this secret. This is the last few characters of the full secret value but is not sufficient for authentication. Helps identify which secret is being used in logs and debugging. + + - **`status`** + + `string`, possible values: `"INACTIVE"` — The current status of this secret. A secret must be ACTIVE to be used for authentication. INACTIVE secrets cannot be used for authentication but are retained for audit purposes. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this secret was last updated. This field is automatically updated by the server when the secret's status changes or other properties are modified. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this API client was last updated. This field is automatically updated by the server whenever the client's configuration changes. + +**Example:** + +```json +{ + "client": { + "audience": [ + "https://api.example.com" + ], + "client_id": "m2morg_1231234233424344", + "create_time": "2024-01-05T14:48:00Z", + "custom_claims": [ + {} + ], + "description": "Service account for automated deployment processes", + "expiry": 3600, + "is_cimd": false, + "is_dcr": false, + "metadata_uri": "https://example.com/client-metadata.json", + "name": "GitHub Actions Deployment Service", + "organization_id": "org_1231234233424344", + "redirect_uris": [ + "https://example.com/callback" + ], + "resource_id": "app_1231234233424344", + "scopes": [ + "deploy:resources", + "read:deployments" + ], + "secrets": [ + {} + ], + "update_time": "2024-01-05T14:48:00Z" + } +} +``` + +### Delete organization API client + +- **Method:** `DELETE` +- **Path:** `/api/v1/organizations/{organization_id}/clients/{client_id}` +- **Tags:** API Auth + +Permanently deletes an API client from an organization. This operation cannot be undone and will revoke all access for the client. All associated secrets will also be invalidated. Use this endpoint to remove unused or compromised clients. + +#### Responses + +##### Status: 200 Organization API client successfully deleted and no longer accessible + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Update organization API client + +- **Method:** `PATCH` +- **Path:** `/api/v1/organizations/{organization_id}/clients/{client_id}` +- **Tags:** API Auth + +Updates an existing organization API client. Only specified fields are modified. + +#### Request Body + +##### Content-Type: application/json + +- **`audience`** + + `array` — The intended recipients of the access tokens issued to this client. Each audience value should be a URI that identifies the API or service that will validate the token. + + **Items:** + + `string` + +- **`custom_claims`** + + `array` — Additional claims to be included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. Keep claims minimal to avoid increasing token size. + + **Items:** + + - **`key`** + + `string` — The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose. + + - **`value`** + + `string` — The value of the custom claim. This value will be included in access tokens issued to the client. + +- **`description`** + + `string` — A detailed explanation of the client's purpose and usage. This helps administrators understand what the client is used for and who manages it. + +- **`expiry`** + + `string`, format: `int64` — Expiry time in seconds for the token generated by the client + +- **`name`** + + `string` — A descriptive name for the API client that helps identify its purpose. This name is displayed in the dashboard and logs. Must be between 1 and 128 characters. + +- **`scopes`** + + `array` — OAuth 2.0 scopes that define the permissions granted to this client. Each scope represents a specific permission or set of permissions. The client can only access resources that match its granted scopes. + + **Items:** + + `string` + +**Example:** + +```json +{ + "audience": [ + "https://api.example.com/api/analytics", + "https://deployment-api.acmecorp.com" + ], + "custom_claims": [ + { + "key": "environment", + "value": "production" + }, + { + "key": "service", + "value": "deployment" + } + ], + "description": "Service account for GitHub Actions to deploy resources to production", + "expiry": 3600, + "name": "GitHub Actions Deployment Service", + "scopes": [ + "deploy:resources", + "read:deployments" + ] +} +``` + +#### Responses + +##### Status: 200 Returns the updated organization API client with all current details reflected in the response, including modified scopes, audience values, and custom claims. + +###### Content-Type: application/json + +- **`client`** + + `object` — Updated details of the client + + - **`audience`** + + `array` — The intended recipients of access tokens issued to this client. Each audience value should be a URI that identifies an API or service. + + **Items:** + + `string` + + - **`client_id`** + + `string` — The unique identifier for this API client. This ID is used to identify the client in API requests and logs. It is automatically generated when the client is created and cannot be modified. + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this API client was created. This field is automatically set by the server and cannot be modified. + + - **`custom_claims`** + + `array` — Additional claims included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. + + **Items:** + + - **`key`** + + `string` — The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose. + + - **`value`** + + `string` — The value of the custom claim. This value will be included in access tokens issued to the client. + + - **`description`** + + `string` — A detailed description of the client's purpose and usage. This helps administrators understand what the client is used for. + + - **`expiry`** + + `string`, format: `int64` — Expiry time in seconds for the token generated by the client + + - **`is_cimd`** + + `boolean` — Indicates if the client was created via Client ID Metadata Document (CIMD). CIMD clients can update their own configuration according to the CIMD specification. + + - **`is_dcr`** + + `boolean` — Indicates if the client was created via Dynamic Client Registration (DCR). Clients created through DCR may have different management and lifecycle policies compared to those created manually. + + - **`metadata_uri`** + + `string` — The URI to the client's metadata, which is utilized to obtain the client's configuration details + + - **`name`** + + `string` — The display name of the API client. This name helps identify the client in the dashboard and logs. + + - **`organization_id`** + + `string` — The ID of the organization that owns this API client. This ID is used to associate the client with the correct organization and enforce organization-specific access controls. + + - **`redirect_uris`** + + `array` — The redirect URI for this API client. This URI is used in the OAuth 2.0 authorization flow to redirect users after authentication. + + **Items:** + + `string` + + - **`resource_id`** + + `string` — The ID of the resource associated with this M2M client. This field is used to link the client to a specific resource in the system. + + - **`scopes`** + + `array` — The OAuth 2.0 scopes granted to this client. These scopes determine what resources and actions the client can access. + + **Items:** + + `string` + + - **`secrets`** + + `array` — List of client secrets associated with this client. Each secret can be used for authentication, but only the most recently created secret is typically active. Secrets are stored securely and their values are never returned after creation. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this secret was created. This field is automatically set by the server and cannot be modified. + + - **`created_by`** + + `string` — The identifier of the user or system that created this secret. This field helps track who created the secret for audit and compliance purposes. + + - **`expire_time`** + + `string`, format: `date-time` — The timestamp when this secret will expire. After this time, the secret cannot be used for authentication regardless of its status. If not set, the secret does not expire. + + - **`id`** + + `string` — The unique identifier for this client secret. This ID is used to reference the secret in API requests for management operations like updating or deleting the secret. + + - **`last_used_time`** + + `string`, format: `date-time` — The timestamp when this secret was last used for authentication. This field helps track secret usage for security monitoring and identifying unused secrets that may be candidates for rotation. + + - **`plain_secret`** + + `string` — The full plaintext secret value. This field is only populated when the secret is first created and is never stored by the server. It must be securely stored by the client application as it cannot be retrieved again. + + - **`secret_suffix`** + + `string` — A suffix that helps identify this secret. This is the last few characters of the full secret value but is not sufficient for authentication. Helps identify which secret is being used in logs and debugging. + + - **`status`** + + `string`, possible values: `"INACTIVE"` — The current status of this secret. A secret must be ACTIVE to be used for authentication. INACTIVE secrets cannot be used for authentication but are retained for audit purposes. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this secret was last updated. This field is automatically updated by the server when the secret's status changes or other properties are modified. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this API client was last updated. This field is automatically updated by the server whenever the client's configuration changes. + +**Example:** + +```json +{ + "client": { + "audience": [ + "https://api.example.com" + ], + "client_id": "m2morg_1231234233424344", + "create_time": "2024-01-05T14:48:00Z", + "custom_claims": [ + {} + ], + "description": "Service account for automated deployment processes", + "expiry": 3600, + "is_cimd": false, + "is_dcr": false, + "metadata_uri": "https://example.com/client-metadata.json", + "name": "GitHub Actions Deployment Service", + "organization_id": "org_1231234233424344", + "redirect_uris": [ + "https://example.com/callback" + ], + "resource_id": "app_1231234233424344", + "scopes": [ + "deploy:resources", + "read:deployments" + ], + "secrets": [ + {} + ], + "update_time": "2024-01-05T14:48:00Z" + } +} +``` + +### Create organization API client secret + +- **Method:** `POST` +- **Path:** `/api/v1/organizations/{organization_id}/clients/{client_id}/secrets` +- **Tags:** API Auth + +Creates a new secret for an organization API client. Returns the plain secret (available only once). + +#### Responses + +##### Status: 201 Client secret created successfully. Returns the new secret ID and the plain secret value (only available at creation time). The secret can be used immediately for authentication. + +###### Content-Type: application/json + +- **`plain_secret`** + + `string` — Client secret value (only returned once at creation) + +- **`secret`** + + `object` — Details of the created client secret + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this secret was created. This field is automatically set by the server and cannot be modified. + + - **`created_by`** + + `string` — The identifier of the user or system that created this secret. This field helps track who created the secret for audit and compliance purposes. + + - **`expire_time`** + + `string`, format: `date-time` — The timestamp when this secret will expire. After this time, the secret cannot be used for authentication regardless of its status. If not set, the secret does not expire. + + - **`id`** + + `string` — The unique identifier for this client secret. This ID is used to reference the secret in API requests for management operations like updating or deleting the secret. + + - **`last_used_time`** + + `string`, format: `date-time` — The timestamp when this secret was last used for authentication. This field helps track secret usage for security monitoring and identifying unused secrets that may be candidates for rotation. + + - **`plain_secret`** + + `string` — The full plaintext secret value. This field is only populated when the secret is first created and is never stored by the server. It must be securely stored by the client application as it cannot be retrieved again. + + - **`secret_suffix`** + + `string` — A suffix that helps identify this secret. This is the last few characters of the full secret value but is not sufficient for authentication. Helps identify which secret is being used in logs and debugging. + + - **`status`** + + `string`, possible values: `"INACTIVE"` — The current status of this secret. A secret must be ACTIVE to be used for authentication. INACTIVE secrets cannot be used for authentication but are retained for audit purposes. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this secret was last updated. This field is automatically updated by the server when the secret's status changes or other properties are modified. + +**Example:** + +```json +{ + "plain_secret": "m2morg_client_secret_xyz123", + "secret": { + "create_time": "2024-01-05T14:48:00Z", + "created_by": "user_12345", + "expire_time": "2025-01-05T14:48:00Z", + "id": "sec_1234abcd5678efgh", + "last_used_time": "2024-02-15T10:30:00Z", + "plain_secret": "sec_1234567890abcdefghijklmnopqrstuvwxyz", + "secret_suffix": "xyzw", + "status": "INACTIVE", + "update_time": "2024-01-10T09:12:00Z" + } +} +``` + +### Delete organization API client secret + +- **Method:** `DELETE` +- **Path:** `/api/v1/organizations/{organization_id}/clients/{client_id}/secrets/{secret_id}` +- **Tags:** API Auth + +Permanently deletes a secret from an organization API client. This operation cannot be undone. + +#### Responses + +##### Status: 200 Client secret successfully deleted and no longer accessible + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Get connection details + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{organization_id}/connections/{id}` +- **Tags:** Connections + +Retrieves the complete configuration and status details for a specific connection by its ID within an organization. Returns all connection properties including provider settings, protocols, and current status. + +#### Responses + +##### Status: 200 Successfully retrieved connection details for the specified organization + +###### Content-Type: application/json + +- **`connection`** + + `object` — Complete connection details including provider configuration, protocol settings, status, and all metadata. Contains everything needed to understand the connection's current state. + + - **`attribute_mapping`** + + `object` — Maps identity provider attributes to user profile fields. For example, {'email': 'user.mail', 'name': 'user.displayName'}. + + - **`configuration_type`** + + `string`, possible values: `"DISCOVERY", "MANUAL"` — How the connection was configured: DISCOVERY (automatic configuration) or MANUAL (administrator configured) + + - **`debug_enabled`** + + `boolean` — Enables testing mode that allows non-HTTPS endpoints. Should only be enabled in development environments, never in production. + + - **`domains`** + + `array` — Domain associated with this connection, used for domain-based authentication flows. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the domain was first created. + + - **`domain`** + + `string` — The business domain name that was configured for allowed email domain functionality (e.g., company.com, subdomain.company.com). + + - **`domain_type`** + + `object` + + - **`environment_id`** + + `string` — The environment ID where this domain is configured. + + - **`id`** + + `string` — Scalekit-generated unique identifier for this domain record. + + - **`organization_id`** + + `string` — The organization to which the domain belongs. + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the domain was last updated. + + - **`verification_method`** + + `string`, possible values: `"ADMIN", "DNS", "NOT_APPLICABLE"` — Method that determines how domain ownership is verified. - ADMIN: domain is marked verified without DNS validation, typically by an admin. - DNS: domain must be verified by adding a TXT record to your DNS configuration. - NOT\_APPLICABLE: verification does not apply to this domain type. + + - **`verification_status`** + + `string`, possible values: `"PENDING", "VERIFIED", "FAILED", "AUTO_VERIFIED"` — Verification status of the domain. - PENDING: DNS TXT record has not been validated yet. - VERIFIED: domain confirmed via DNS TXT record validation or admin approval. - AUTO\_VERIFIED: domain verified automatically without DNS changes. - FAILED: DNS TXT record was not validated within the verification window. + + - **`enabled`** + + `boolean` — Controls whether users can sign in using this connection. When false, the connection exists but cannot be used for authentication. + + - **`id`** + + `string` — Unique identifier for this connection. Used in API calls to reference this specific connection. + + - **`key_id`** + + `string` — Alternative identifier for this connection, typically used in frontend applications or URLs. + + - **`oauth_config`** + + `object` — Configuration details for OAuth connections. Present only when type is OAUTH. + + - **`access_type`** + + `string` — Access Type + + - **`authorize_uri`** + + `string` — Authorize URI + + - **`client_id`** + + `string` — Client ID + + - **`client_secret`** + + `string` — Client Secret + + - **`custom_scope_name`** + + `string` — Custom Scope Name + + - **`pkce_enabled`** + + `boolean` — PKCE Enabled + + - **`prompt`** + + `string` — Prompt for the user + + - **`redirect_uri`** + + `string` — Redirect URI + + - **`scopes`** + + `array` — OIDC Scopes + + **Items:** + + `string` + + - **`sync_user_profile_on_login`** + + `boolean` — Indicates whether user profiles should be synchronized with the identity provider upon each log-in. + + - **`tenant_id`** + + `string` — Microsoft Entra tenant ID. Required when using a single-tenant or multi-tenant app registered in Microsoft Entra. Leave empty to use the common endpoint. + + - **`token_access_type`** + + `string` — Token Access Type + + - **`token_uri`** + + `string` — Token URI + + - **`use_platform_creds`** + + `boolean` — Use Scalekit credentials + + - **`user_info_uri`** + + `string` — User Info URI + + - **`oidc_config`** + + `object` — Configuration details for OpenID Connect (OIDC) connections. Present only when type is OIDC. + + - **`authorize_uri`** + + `string` — Authorize URI + + - **`backchannel_logout_redirect_uri`** + + `string` — backchannel logout redirect uri where idp sends logout\_token + + - **`client_id`** + + `string` — Client ID + + - **`client_secret`** + + `string` — Client Secret + + - **`discovery_endpoint`** + + `string` — Discovery Endpoint + + - **`idp_logout_required`** + + `boolean` — Enable IDP logout + + - **`issuer`** + + `string` — Issuer URL + + - **`jit_provisioning_with_sso_enabled`** + + `boolean` — Indicates if Just In Time user provisioning is enabled for the connection + + - **`jwks_uri`** + + `string` — JWKS URI + + - **`pkce_enabled`** + + `boolean` — PKCE Enabled + + - **`post_logout_redirect_uri`** + + `string` — post logout redirect uri + + - **`redirect_uri`** + + `string` — Redirect URI + + - **`scopes`** + + `array` — OIDC Scopes + + **Items:** + + `string`, possible values: `"openid", "profile", "email", "address", "phone"` + + - **`sync_user_profile_on_login`** + + `boolean` — Indicates whether user profiles should be synchronized with the identity provider upon each log-in. + + - **`token_auth_type`** + + `string`, possible values: `"URL_PARAMS", "BASIC_AUTH"` — Token Auth Type + + - **`token_uri`** + + `string` — Token URI + + - **`user_info_uri`** + + `string` — User Info URI + + - **`organization_id`** + + `string` — Identifier of the organization that owns this connection. Connections are typically scoped to a single organization. + + - **`passwordless_config`** + + `object` — Configuration details for Magic Link authentication. Present only when type is MAGIC\_LINK. + + - **`code_challenge_length`** + + `integer`, format: `int64` — Code Challenge Length + + - **`code_challenge_type`** + + `string`, possible values: `"NUMERIC", "ALPHANUMERIC"` — Code Challenge Type + + - **`enforce_same_browser_origin`** + + `boolean` — Enforce Same Browser Origin + + - **`frequency`** + + `integer`, format: `int64` — Link Frequency + + - **`regenerate_passwordless_credentials_on_resend`** + + `boolean` — Regenerate the + + - **`type`** + + `string`, possible values: `"LINK", "OTP", "LINK_OTP"` — Passwordless Type + + - **`validity`** + + `integer`, format: `int64` — Link Validity in Seconds + + - **`provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Identity provider service that handles authentication (such as OKTA, Google, Azure AD, or a custom provider) + + - **`provider_key`** + + `string` — Key ID of the identity provider service that handles authentication + + - **`saml_config`** + + `object` — Configuration details for SAML connections. Present only when type is SAML. + + - **`allow_idp_initiated_login`** + + `boolean` — Allow IDP Initiated Login + + - **`assertion_encrypted`** + + `boolean` — Assertion Encrypted + + - **`certificate_id`** + + `string` — Certificate ID + + - **`default_redirect_uri`** + + `string` — Default Redirect URI + + - **`force_authn`** + + `boolean` — Force Authn + + - **`idp_certificates`** + + `array` — IDP Certificates + + **Items:** + + - **`certificate`** + + `string` — IDP Certificate + + - **`create_time`** + + `string`, format: `date-time` — Certificate Creation Time + + - **`expiry_time`** + + `string`, format: `date-time` — Certificate Expiry Time + + - **`id`** + + `string` — Certificate ID + + - **`issuer`** + + `string` — Certificate Issuer + + - **`idp_entity_id`** + + `string` — IDP Entity ID + + - **`idp_metadata_url`** + + `string` — IDP Metadata URL + + - **`idp_name_id_format`** + + `string`, possible values: `"UNSPECIFIED", "EMAIL", "TRANSIENT", "PERSISTENT"` — IDP Name ID Format + + - **`idp_slo_request_binding`** + + `string`, possible values: `"HTTP_POST", "HTTP_REDIRECT"` — IDP SLO Request Binding + + - **`idp_slo_required`** + + `boolean` — Enable IDP logout + + - **`idp_slo_url`** + + `string` — IDP SLO URL + + - **`idp_sso_request_binding`** + + `string`, possible values: `"HTTP_POST", "HTTP_REDIRECT"` — IDP SSO Request Binding + + - **`idp_sso_url`** + + `string` — IDP SSO URL + + - **`jit_provisioning_with_sso_enabled`** + + `boolean` — Indicates if Just In Time user provisioning is enabled for the connection + + - **`saml_signing_option`** + + `string`, possible values: `"NO_SIGNING", "SAML_ONLY_RESPONSE_SIGNING", "SAML_ONLY_ASSERTION_SIGNING", "SAML_RESPONSE_ASSERTION_SIGNING", "SAML_RESPONSE_OR_ASSERTION_SIGNING"` — SAML Signing Option + + - **`sp_assertion_url`** + + `string` — SP Assertion URL + + - **`sp_entity_id`** + + `string` — SP Entity ID + + - **`sp_metadata_url`** + + `string` — SP Metadata URL + + - **`sp_slo_url`** + + `string` — Service Provider SLO url + + - **`sync_user_profile_on_login`** + + `boolean` — Indicates whether user profiles should be synchronized with the identity provider upon each log-in. + + - **`ui_button_title`** + + `string` — UI Button Title + + - **`want_request_signed`** + + `boolean` — Want Request Signed + + - **`static_config`** + + `object` — Static configuration for custom connections. Present only when type is BASIC, BEARER, API\_KEY, or custom. + + - **`static_config`** + + `object` + + - **`status`** + + `string`, possible values: `"DRAFT", "IN_PROGRESS", "COMPLETED"` — Current configuration status of the connection. Possible values include IN\_PROGRESS, CONFIGURED, and ERROR. + + - **`test_connection_uri`** + + `string` — URI that can be used to test this connection. Visit this URL to verify the connection works correctly. + + - **`type`** + + `string`, possible values: `"OIDC", "SAML", "PASSWORD", "OAUTH", "PASSWORDLESS", "BASIC", "BEARER", "API_KEY", "WEBAUTHN"` — Authentication protocol used by this connection. Can be OIDC (OpenID Connect), SAML, OAUTH, or MAGIC\_LINK. + + - **`webauthn_config`** + + `object` — Configuration details for WebAuthn (passkeys). Present only when type is WEBAUTHN. + + - **`attestation`** + + `object` + + - **`conveyance_preference`** + + `string` + + - **`enterprise_approved_ids`** + + `array` + + **Items:** + + `string` + + - **`authenticator_selection`** + + `object` + + - **`authenticator_attachment`** + + `string` + + - **`user_verification`** + + `string` + + - **`authenticators`** + + `object` + + - **`desired_authenticator_status`** + + `array` — provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate\_status set to true. + + **Items:** + + `string`, default: `"[]"` + + - **`undesired_authenticator_status`** + + `array` — provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate\_status set to true. + + **Items:** + + `string`, default: `"['ATTESTATION_KEY_COMPROMISE', 'USER_VERIFICATION_BYPASS', 'USER_KEY_REMOTE_COMPROMISE', 'USER_KEY_PHYSICAL_COMPROMISE', 'REVOKED']"` + + - **`validate_anchors`** + + `boolean` — when set to true enables the validation of the attestation statement against the trust anchor from the metadata statement. + + - **`validate_attestation_type`** + + `boolean` — when set to true enables the validation of the attestation statements type against the known types the authenticator can produce. + + - **`validate_entry`** + + `boolean` — requires that the provided metadata has an entry for the given authenticator to be considered valid. By default an AAGUID which has a zero value should fail validation if validate\_entry\_permit\_zero\_aaguid is not provided with the value of true. + + - **`validate_entry_permit_zero_aaguid`** + + `boolean` — is an option that permits a zero'd AAGUID from an attestation statement to automatically pass metadata validations. Generally helpful to use with validate\_entry. + + - **`validate_status`** + + `boolean` — when set to true enables the validation of the attestation statements AAGUID against the desired and undesired lists + + - **`enable_auto_registration`** + + `boolean` — Enable auto registration for WebAuthn + + - **`enable_conditional_login`** + + `boolean` — Allow autofill of passkeys in login page + + - **`rp`** + + `object` + + - **`ids`** + + `array` + + **Items:** + + `string` + + - **`origins`** + + `array` + + **Items:** + + `string` + + - **`show_passkey_button`** + + `boolean` — Show passkey button on login screen + + - **`timeout`** + + `object` + + - **`login`** + + `string`, default: `"\"300s\""` — Login timeout duration + + - **`login_uvd`** + + `string`, default: `"\"300s\""` — Login timeout duration when user verification is discouraged + + - **`registration`** + + `string`, default: `"\"300s\""` — Registration timeout duration + + - **`registration_uvd`** + + `string`, default: `"\"300s\""` — Registration timeout duration when user verification is discouraged + +**Example:** + +```json +{ + "connection": { + "attribute_mapping": { + "additionalProperty": "" + }, + "configuration_type": "MANUAL", + "debug_enabled": true, + "domains": [ + { + "name": "example.com" + } + ], + "enabled": false, + "id": "conn_2123312131125533", + "key_id": "", + "oauth_config": null, + "oidc_config": null, + "organization_id": "org_2123312131125533", + "passwordless_config": null, + "provider": "OKTA", + "provider_key": "google", + "saml_config": null, + "static_config": null, + "status": "IN_PROGRESS", + "test_connection_uri": "https://auth.example.com/test-connection/conn_2123312131125533", + "type": "OIDC", + "webauthn_config": null + } +} +``` + +### Delete SSO connection + +- **Method:** `DELETE` +- **Path:** `/api/v1/organizations/{organization_id}/connections/{id}` +- **Tags:** Connections + +Deletes an SSO connection from the specified organization by connection ID. Use this endpoint when an identity provider integration is no longer needed for the organization. Returns an empty response after the SSO connection is deleted successfully. + +#### Responses + +##### Status: 200 SSO connection deleted successfully + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Disable SSO connection + +- **Method:** `PATCH` +- **Path:** `/api/v1/organizations/{organization_id}/connections/{id}:disable` +- **Tags:** Connections + +Deactivate an existing connection for the specified organization. When disabled, users cannot authenticate using this connection. This endpoint changes the connection state from enabled to disabled without modifying other configuration settings + +#### Responses + +##### Status: 200 Connection disabled successfully + +###### Content-Type: application/json + +- **`enabled`** + + `boolean` — Current state of the connection after the operation. True means the connection is now enabled and can be used for authentication. + +- **`error_message`** + + `string` — Error message if the operation fails + +**Example:** + +```json +{ + "enabled": true, + "error_message": "placeholder" +} +``` + +### Enable SSO connection + +- **Method:** `PATCH` +- **Path:** `/api/v1/organizations/{organization_id}/connections/{id}:enable` +- **Tags:** Connections + +Activate an existing connection for the specified organization. When enabled, users can authenticate using this connection. This endpoint changes the connection state from disabled to enabled without modifying other configuration settings + +#### Responses + +##### Status: 200 Connection enabled successfully + +###### Content-Type: application/json + +- **`enabled`** + + `boolean` — Current state of the connection after the operation. True means the connection is now enabled and can be used for authentication. + +- **`error_message`** + + `string` — Error message if the operation fails + +**Example:** + +```json +{ + "enabled": true, + "error_message": "placeholder" +} +``` + +### List organization directories + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{organization_id}/directories` +- **Tags:** Directory + +#### Responses + +##### Status: 200 Successfully retrieved the list of directories for the organization + +###### Content-Type: application/json + +- **`directories`** + + `array` — List of directories associated with the organization + + **Items:** + + - **`attribute_mappings`** + + `object` — Mappings between directory attributes and Scalekit user and group attributes + + - **`attributes`** + + `array` + + **Items:** + + - **`key`** + + `string` + + - **`map_to`** + + `string` + + - **`directory_endpoint`** + + `string` — The endpoint URL generated by Scalekit for synchronizing users and groups from the Directory Provider + + - **`directory_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "JUMPCLOUD", "PING_IDENTITY"` — Identity provider connected to this directory + + - **`directory_type`** + + `string`, possible values: `"SCIM", "LDAP", "POLL"` — Type of the directory, indicating the protocol or standard used for synchronization + + - **`email`** + + `string` — Email Id associated with Directory whose access will be used for polling + + - **`enabled`** + + `boolean` — Indicates whether the directory is currently enabled and actively synchronizing users and groups + + - **`groups_tracked`** + + `string` — It indicates if all groups are tracked or select groups are tracked + + - **`id`** + + `string` — Unique identifier of the directory + + - **`last_synced_at`** + + `string`, format: `date-time` — Timestamp of the last successful synchronization of users and groups from the Directory Provider + + - **`name`** + + `string` — Name of the directory, typically representing the connected Directory provider + + - **`organization_id`** + + `string` — Unique identifier of the organization to which the directory belongs + + - **`role_assignments`** + + `object` — Role assignments associated with the directory, defining group based role assignments + + - **`assignments`** + + `array` + + **Items:** + + - **`group_id`** + + `string` — group ID for the role mapping + + - **`role_name`** + + `string` + + - **`secrets`** + + `array` — List of secrets used for authenticating and synchronizing with the Directory Provider + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Creation Time + + - **`directory_id`** + + `string` — Directory ID + + - **`expire_time`** + + `string`, format: `date-time` — Expiry Time + + - **`id`** + + `string` + + - **`last_used_time`** + + `string`, format: `date-time` — Last Used Time + + - **`secret_suffix`** + + `string` — Secret Suffix + + - **`status`** + + `string`, possible values: `"INACTIVE"` — Secret Status + + - **`stats`** + + `object` — Statistics and metrics related to the directory, such as synchronization status and error counts + + - **`group_updated_at`** + + `string`, format: `date-time` — Max time of Group Updated At for Directory + + - **`total_groups`** + + `integer`, format: `int32` — Total Groups in the Directory + + - **`total_users`** + + `integer`, format: `int32` — Total Users in the Directory + + - **`user_updated_at`** + + `string`, format: `date-time` — Max time of User Updated At for Directory + + - **`status`** + + `string` — Directory Status + + - **`total_groups`** + + `integer`, format: `int32` — Total number of groups in the directory + + - **`total_users`** + + `integer`, format: `int32` — Total number of users in the directory + +**Example:** + +```json +{ + "directories": [ + { + "attribute_mappings": null, + "directory_endpoint": "https://yourapp.scalekit.com/api/v1/directoies/dir_123212312/scim/v2", + "directory_provider": "OKTA", + "directory_type": "SCIM", + "email": "john.doe@scalekit.cloud", + "enabled": true, + "groups_tracked": "ALL", + "id": "dir_121312434123312", + "last_synced_at": "2024-10-01T00:00:00Z", + "name": "Azure AD", + "organization_id": "org_121312434123312", + "role_assignments": null, + "secrets": [ + {} + ], + "stats": null, + "status": "IN_PROGRESS", + "total_groups": 10, + "total_users": 10 + } + ] +} +``` + +### List directory groups + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{organization_id}/directories/{directory_id}/groups` +- **Tags:** Directory + +Retrieves all groups from a specified directory. Use this endpoint to view group structures from your connected identity provider. + +#### Responses + +##### Status: 200 Successfully retrieved the list of groups from the specified directory + +###### Content-Type: application/json + +- **`groups`** + + `array` — List of directory groups retrieved from the specified directory + + **Items:** + + - **`display_name`** + + `string` — Display Name + + - **`group_detail`** + + `object` — Complete Group Details Payload + + - **`id`** + + `string` — Group ID + + - **`total_users`** + + `integer`, format: `int32` — Total Users in the Group + + - **`updated_at`** + + `string`, format: `date-time` — Updated At + +- **`next_page_token`** + + `string` — Token to retrieve the next page of results. Use this token in the 'page\_token' field of the next request + +- **`prev_page_token`** + + `string` — Token to retrieve the previous page of results. Use this token in the 'page\_token' field of the next request + +- **`total_size`** + + `integer`, format: `int64` — Total number of groups matching the request criteria, regardless of pagination + +**Example:** + +```json +{ + "groups": [ + { + "display_name": "Admins", + "group_detail": {}, + "id": "dirgroup_121312434123312", + "total_users": 10, + "updated_at": "2024-10-01T00:00:00Z" + } + ], + "next_page_token": "", + "prev_page_token": "", + "total_size": 1 +} +``` + +### List directory users + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{organization_id}/directories/{directory_id}/users` +- **Tags:** Directory + +Retrieves a list of all users within a specified directory for an organization. This endpoint allows you to view user accounts associated with your connected Directory Providers. + +#### Responses + +##### Status: 200 Successfully retrieved the list of users from the specified directory + +###### Content-Type: application/json + +- **`next_page_token`** + + `string` — Token for pagination. Use this token in the 'page\_token' field of the next request to fetch the subsequent page of users + +- **`prev_page_token`** + + `string` — Token for pagination. Use this token in the 'page\_token' field of the next request to fetch the prior page of users + +- **`total_size`** + + `integer`, format: `int64` — Total number of users available in the directory that match the request criteria + +- **`users`** + + `array` — List of directory users retrieved from the specified directory + + **Items:** + + - **`email`** + + `string` — Email + + - **`emails`** + + `array` — Emails + + **Items:** + + `string` + + - **`family_name`** + + `string` — Last Name + + - **`given_name`** + + `string` — First Name + + - **`groups`** + + `array` — Groups + + **Items:** + + - **`display_name`** + + `string` — Display Name + + - **`group_detail`** + + `object` — Complete Group Details Payload + + - **`id`** + + `string` — Group ID + + - **`total_users`** + + `integer`, format: `int32` — Total Users in the Group + + - **`updated_at`** + + `string`, format: `date-time` — Updated At + + - **`id`** + + `string` — User ID + + - **`preferred_username`** + + `string` — Preferred Username + + - **`updated_at`** + + `string`, format: `date-time` — Updated At + + - **`user_detail`** + + `object` — Complete User Details Payload + +**Example:** + +```json +{ + "next_page_token": "", + "prev_page_token": "", + "total_size": 1, + "users": [ + { + "email": "johndoe", + "emails": [ + "" + ], + "family_name": "Doe", + "given_name": "John", + "groups": [ + {} + ], + "id": "diruser_121312434123312", + "preferred_username": "johndoe", + "updated_at": "2024-10-01T00:00:00Z", + "user_detail": {} + } + ] +} +``` + +### Get directory details + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{organization_id}/directories/{id}` +- **Tags:** Directory + +Retrieves detailed information about a specific directory within an organization + +#### Responses + +##### Status: 200 Successfully retrieved directory details + +###### Content-Type: application/json + +- **`directory`** + + `object` — Detailed information about the requested directory + + - **`attribute_mappings`** + + `object` — Mappings between directory attributes and Scalekit user and group attributes + + - **`attributes`** + + `array` + + **Items:** + + - **`key`** + + `string` + + - **`map_to`** + + `string` + + - **`directory_endpoint`** + + `string` — The endpoint URL generated by Scalekit for synchronizing users and groups from the Directory Provider + + - **`directory_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "JUMPCLOUD", "PING_IDENTITY"` — Identity provider connected to this directory + + - **`directory_type`** + + `string`, possible values: `"SCIM", "LDAP", "POLL"` — Type of the directory, indicating the protocol or standard used for synchronization + + - **`email`** + + `string` — Email Id associated with Directory whose access will be used for polling + + - **`enabled`** + + `boolean` — Indicates whether the directory is currently enabled and actively synchronizing users and groups + + - **`groups_tracked`** + + `string` — It indicates if all groups are tracked or select groups are tracked + + - **`id`** + + `string` — Unique identifier of the directory + + - **`last_synced_at`** + + `string`, format: `date-time` — Timestamp of the last successful synchronization of users and groups from the Directory Provider + + - **`name`** + + `string` — Name of the directory, typically representing the connected Directory provider + + - **`organization_id`** + + `string` — Unique identifier of the organization to which the directory belongs + + - **`role_assignments`** + + `object` — Role assignments associated with the directory, defining group based role assignments + + - **`assignments`** + + `array` + + **Items:** + + - **`group_id`** + + `string` — group ID for the role mapping + + - **`role_name`** + + `string` + + - **`secrets`** + + `array` — List of secrets used for authenticating and synchronizing with the Directory Provider + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Creation Time + + - **`directory_id`** + + `string` — Directory ID + + - **`expire_time`** + + `string`, format: `date-time` — Expiry Time + + - **`id`** + + `string` + + - **`last_used_time`** + + `string`, format: `date-time` — Last Used Time + + - **`secret_suffix`** + + `string` — Secret Suffix + + - **`status`** + + `string`, possible values: `"INACTIVE"` — Secret Status + + - **`stats`** + + `object` — Statistics and metrics related to the directory, such as synchronization status and error counts + + - **`group_updated_at`** + + `string`, format: `date-time` — Max time of Group Updated At for Directory + + - **`total_groups`** + + `integer`, format: `int32` — Total Groups in the Directory + + - **`total_users`** + + `integer`, format: `int32` — Total Users in the Directory + + - **`user_updated_at`** + + `string`, format: `date-time` — Max time of User Updated At for Directory + + - **`status`** + + `string` — Directory Status + + - **`total_groups`** + + `integer`, format: `int32` — Total number of groups in the directory + + - **`total_users`** + + `integer`, format: `int32` — Total number of users in the directory + +**Example:** + +```json +{ + "directory": { + "attribute_mappings": null, + "directory_endpoint": "https://yourapp.scalekit.com/api/v1/directoies/dir_123212312/scim/v2", + "directory_provider": "OKTA", + "directory_type": "SCIM", + "email": "john.doe@scalekit.cloud", + "enabled": true, + "groups_tracked": "ALL", + "id": "dir_121312434123312", + "last_synced_at": "2024-10-01T00:00:00Z", + "name": "Azure AD", + "organization_id": "org_121312434123312", + "role_assignments": null, + "secrets": [ + {} + ], + "stats": null, + "status": "IN_PROGRESS", + "total_groups": 10, + "total_users": 10 + } +} +``` + +### Disable a directory + +- **Method:** `PATCH` +- **Path:** `/api/v1/organizations/{organization_id}/directories/{id}:disable` +- **Tags:** Directory + +Stops synchronization of users and groups from a specified directory within an organization. This operation prevents further updates from the connected Directory provider + +#### Responses + +##### Status: 200 Successfully disabled the directory + +###### Content-Type: application/json + +- **`enabled`** + + `boolean` — Specifies the directory's state after the toggle operation. A value of \`true\` indicates that the directory is enabled and actively synchronizing users and groups. A value of \`false\` means the directory is disabled, halting synchronization + +- **`error_message`** + + `string` — Contains a human-readable error message if the toggle operation encountered an issue. If the operation was successful, this field will be empty + +**Example:** + +```json +{ + "enabled": true, + "error_message": "The directory is already enabled" +} +``` + +### Enable a directory + +- **Method:** `PATCH` +- **Path:** `/api/v1/organizations/{organization_id}/directories/{id}:enable` +- **Tags:** Directory + +Activates a directory within an organization, allowing it to synchronize users and groups with the connected Directory provider + +#### Responses + +##### Status: 200 Success + +###### Content-Type: application/json + +- **`enabled`** + + `boolean` — Specifies the directory's state after the toggle operation. A value of \`true\` indicates that the directory is enabled and actively synchronizing users and groups. A value of \`false\` means the directory is disabled, halting synchronization + +- **`error_message`** + + `string` — Contains a human-readable error message if the toggle operation encountered an issue. If the operation was successful, this field will be empty + +**Example:** + +```json +{ + "enabled": true, + "error_message": "The directory is already enabled" +} +``` + +### List Domains + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{organization_id}/domains` +- **Tags:** Domains + +Retrieves a paginated list of all domains configured for the specified organization. + +Domain types: + +- ALLOWED\_EMAIL\_DOMAIN: Trusted domains used to suggest the organization in the organization switcher during sign-in/sign-up (auth-method agnostic). +- ORGANIZATION\_DOMAIN: SSO discovery domains used to route users to the correct SSO provider and enforce SSO. + +#### Responses + +##### Status: 200 Successfully retrieved the list of domains. + +###### Content-Type: application/json + +- **`domains`** + + `array` — Array of domain objects containing all domain details including verification status and configuration. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the domain was first created. + + - **`domain`** + + `string` — The business domain name that was configured for allowed email domain functionality (e.g., company.com, subdomain.company.com). + + - **`domain_type`** + + `object` + + - **`environment_id`** + + `string` — The environment ID where this domain is configured. + + - **`id`** + + `string` — Scalekit-generated unique identifier for this domain record. + + - **`organization_id`** + + `string` — The organization to which the domain belongs. + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the domain was last updated. + + - **`verification_method`** + + `string`, possible values: `"ADMIN", "DNS", "NOT_APPLICABLE"` — Method that determines how domain ownership is verified. - ADMIN: domain is marked verified without DNS validation, typically by an admin. - DNS: domain must be verified by adding a TXT record to your DNS configuration. - NOT\_APPLICABLE: verification does not apply to this domain type. + + - **`verification_status`** + + `string`, possible values: `"PENDING", "VERIFIED", "FAILED", "AUTO_VERIFIED"` — Verification status of the domain. - PENDING: DNS TXT record has not been validated yet. - VERIFIED: domain confirmed via DNS TXT record validation or admin approval. - AUTO\_VERIFIED: domain verified automatically without DNS changes. - FAILED: DNS TXT record was not validated within the verification window. + +- **`page_number`** + + `integer`, format: `int32` — Current page number in the pagination sequence. + +- **`page_size`** + + `integer`, format: `int32` — Number of domains returned in this page. + +**Example:** + +```json +{ + "domains": [ + { + "create_time": "2025-09-01T12:14:43.100000Z", + "domain": "customerdomain.com", + "domain_type": "ORGANIZATION_DOMAIN", + "environment_id": "env_58345499215790610", + "id": "dom_88351643129225005", + "organization_id": "org_81667076086825451", + "update_time": "2025-09-01T12:14:43.110455Z", + "verification_method": "ADMIN", + "verification_status": "AUTO_VERIFIED" + } + ], + "page_number": 1, + "page_size": 1 +} +``` + +### Create Domain + +- **Method:** `POST` +- **Path:** `/api/v1/organizations/{organization_id}/domains` +- **Tags:** Domains + +Creates and associates a domain with an organization. + +Use one of the following domain types: + +- ALLOWED\_EMAIL\_DOMAIN: Adds a trusted email domain for organization suggestions in the organization switcher during sign-in/sign-up (auth-method agnostic). +- ORGANIZATION\_DOMAIN: Enables SSO domain discovery. If a user signs in with a matching email domain, Scalekit redirects them to the organization’s SSO provider and enforces SSO. + +The domain must be a valid business domain that you control. Public/disposable domains (e.g., gmail.com) are blocked for security. + +#### Request Body + +##### Content-Type: application/json + +- **`domain`** + + `string` — The domain name to be configured. Must be a valid business domain you control. Public and disposable domains (gmail.com, outlook.com, etc.) are automatically blocked for security. + +- **`domain_type`** + + `string`, possible values: `"ALLOWED_EMAIL_DOMAIN", "ORGANIZATION_DOMAIN"` — The domain type. - ALLOWED\_EMAIL\_DOMAIN: trusted domain used to suggest the organization in the organization switcher during sign-in/sign-up. - ORGANIZATION\_DOMAIN: SSO discovery domain used to route users to the correct SSO provider and enforce SSO. + +**Example:** + +```json +{ + "domain": "customerdomain.com", + "domain_type": "ORGANIZATION_DOMAIN" +} +``` + +#### Responses + +##### Status: 200 Successfully created the domain. + +###### Content-Type: application/json + +- **`domain`** + + `object` — The newly created domain object with all configuration details and system-generated identifiers. + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the domain was first created. + + - **`domain`** + + `string` — The business domain name that was configured for allowed email domain functionality (e.g., company.com, subdomain.company.com). + + - **`domain_type`** + + `object` + + - **`environment_id`** + + `string` — The environment ID where this domain is configured. + + - **`id`** + + `string` — Scalekit-generated unique identifier for this domain record. + + - **`organization_id`** + + `string` — The organization to which the domain belongs. + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the domain was last updated. + + - **`verification_method`** + + `string`, possible values: `"ADMIN", "DNS", "NOT_APPLICABLE"` — Method that determines how domain ownership is verified. - ADMIN: domain is marked verified without DNS validation, typically by an admin. - DNS: domain must be verified by adding a TXT record to your DNS configuration. - NOT\_APPLICABLE: verification does not apply to this domain type. + + - **`verification_status`** + + `string`, possible values: `"PENDING", "VERIFIED", "FAILED", "AUTO_VERIFIED"` — Verification status of the domain. - PENDING: DNS TXT record has not been validated yet. - VERIFIED: domain confirmed via DNS TXT record validation or admin approval. - AUTO\_VERIFIED: domain verified automatically without DNS changes. - FAILED: DNS TXT record was not validated within the verification window. + +**Example:** + +```json +{ + "domain": { + "create_time": "2025-09-01T12:14:43.100000Z", + "domain": "customerdomain.com", + "domain_type": "ORGANIZATION_DOMAIN", + "environment_id": "env_58345499215790610", + "id": "dom_88351643129225005", + "organization_id": "org_81667076086825451", + "update_time": "2025-09-01T12:14:43.110455Z", + "verification_method": "ADMIN", + "verification_status": "AUTO_VERIFIED" + } +} +``` + +##### Status: 400 Invalid request — common causes invalid domain format, public or disposable domain, or domain already exists. + +###### Content-Type: application/json + +- **`debug_info`** + + `object` — Describes additional debugging info. + + - **`detail`** + + `string` — Additional debugging information provided by the server. + + - **`stack_entries`** + + `array` — The stack trace entries indicating where the error occurred. + + **Items:** + + `string` + +- **`error_code`** + + `string` + +- **`help_info`** + + `object` — HelpInfo provides documentation links attached to an error response. When present in ErrorInfo, clients should surface these links to help developers resolve the error. For example, a missing required field error may include a link to the relevant guide. + + - **`links`** + + `array` — One or more links relevant to resolving the error. + + **Items:** + + - **`description`** + + `string` — Human-readable label for the link (e.g. "User verification flow"). + + - **`url`** + + `string` — Absolute URL to the documentation page (e.g. "https\://docs.scalekit.com/..."). + +- **`localized_message_info`** + + `object` + + - **`locale`** + + `string` + + - **`message`** + + `string` + +- **`request_info`** + + `object` — Contains metadata about the request that clients can attach when filing a bug or providing other forms of feedback. + + - **`request_id`** + + `string` — An opaque string that should only be interpreted by the service generating it. For example, it can be used to identify requests in the service's logs. + + - **`serving_data`** + + `string` — Any data that was used to serve this request. For example, an encrypted stack trace that can be sent back to the service provider for debugging. + +- **`resource_info`** + + `object` — Describes the resource that is being accessed. + + - **`description`** + + `string` — Describes what error is encountered when accessing this resource. For example, updating a cloud project may require the \`writer\` permission on the developer console project. + + - **`owner`** + + `string` + + - **`required_permissions`** + + `array` — The required permissions needed to access the resource. + + **Items:** + + `string` + + - **`resource_name`** + + `string` + + - **`user`** + + `string` + +- **`tool_error_info`** + + `object` + + - **`execution_id`** + + `string` + + - **`tool_error_code`** + + `string` + + - **`tool_error_message`** + + `string` + +- **`validation_error_info`** + + `object` — Describes violations in a client request. This error type focuses on the syntactic aspects of the request. + + - **`field_violations`** + + `array` — Describes all violations in a client request. + + **Items:** + + - **`constraint`** + + `string` + + - **`description`** + + `string` — A description of why the request element is bad. + + - **`field`** + + `string` + +**Example:** + +```json +{ + "debug_info": { + "detail": "", + "stack_entries": [ + "" + ] + }, + "error_code": "", + "help_info": { + "links": [ + {} + ] + }, + "localized_message_info": { + "locale": "", + "message": "" + }, + "request_info": { + "request_id": "", + "serving_data": "" + }, + "resource_info": { + "description": "", + "owner": "", + "required_permissions": [ + "" + ], + "resource_name": "", + "user": "" + }, + "tool_error_info": { + "execution_id": "", + "tool_error_code": "", + "tool_error_message": "" + }, + "validation_error_info": { + "field_violations": [ + {} + ] + } +} +``` + +### Get Domain + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{organization_id}/domains/{id}` +- **Tags:** Domains + +Retrieves complete details for a domain including domain type, timestamps, and configuration information. + +#### Responses + +##### Status: 200 Successfully retrieved the domain details. + +###### Content-Type: application/json + +- **`domain`** + + `object` — The requested domain object with complete details including domain type, timestamps and configuration. + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the domain was first created. + + - **`domain`** + + `string` — The business domain name that was configured for allowed email domain functionality (e.g., company.com, subdomain.company.com). + + - **`domain_type`** + + `object` + + - **`environment_id`** + + `string` — The environment ID where this domain is configured. + + - **`id`** + + `string` — Scalekit-generated unique identifier for this domain record. + + - **`organization_id`** + + `string` — The organization to which the domain belongs. + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the domain was last updated. + + - **`verification_method`** + + `string`, possible values: `"ADMIN", "DNS", "NOT_APPLICABLE"` — Method that determines how domain ownership is verified. - ADMIN: domain is marked verified without DNS validation, typically by an admin. - DNS: domain must be verified by adding a TXT record to your DNS configuration. - NOT\_APPLICABLE: verification does not apply to this domain type. + + - **`verification_status`** + + `string`, possible values: `"PENDING", "VERIFIED", "FAILED", "AUTO_VERIFIED"` — Verification status of the domain. - PENDING: DNS TXT record has not been validated yet. - VERIFIED: domain confirmed via DNS TXT record validation or admin approval. - AUTO\_VERIFIED: domain verified automatically without DNS changes. - FAILED: DNS TXT record was not validated within the verification window. + +**Example:** + +```json +{ + "domain": { + "create_time": "2025-09-01T12:14:43.100000Z", + "domain": "customerdomain.com", + "domain_type": "ORGANIZATION_DOMAIN", + "environment_id": "env_58345499215790610", + "id": "dom_88351643129225005", + "organization_id": "org_81667076086825451", + "update_time": "2025-09-01T12:14:43.110455Z", + "verification_method": "ADMIN", + "verification_status": "AUTO_VERIFIED" + } +} +``` + +### Delete Domain + +- **Method:** `DELETE` +- **Path:** `/api/v1/organizations/{organization_id}/domains/{id}` +- **Tags:** Domains + +Permanently removes a domain record from an organization. + +- Deleting an ORGANIZATION\_DOMAIN disables SSO routing/enforcement for that domain. +- Deleting an ALLOWED\_EMAIL\_DOMAIN stops organization suggestions for users with that email domain. + +#### Responses + +##### Status: 200 Domain successfully deleted. + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Upsert organization user setting + +- **Method:** `PATCH` +- **Path:** `/api/v1/organizations/{organization_id}/settings/usermanagement` +- **Tags:** Organizations + +Upsert user management settings for an organization + +#### Request Body + +##### Content-Type: application/json + +- **`settings`** + + `object` — The new values for the setting fields to patch. + + - **`max_allowed_users`** + + `integer`, format: `int32` — Maximum number of users allowed in the organization. When nil (not set), there feature is not enabled. When explicitly set to zero, it also means no limit. When set to a positive integer, it enforces the maximum user limit. + +**Example:** + +```json +{ + "settings": { + "max_allowed_users": 100 + } +} +``` + +#### Responses + +##### Status: 200 Returns the updated organization setting. + +###### Content-Type: application/json + +- **`settings`** + + `object` — The updated setting. + + - **`max_allowed_users`** + + `integer`, format: `int32` — Maximum number of users allowed in the organization. When nil (not set), there feature is not enabled. When explicitly set to zero, it also means no limit. When set to a positive integer, it enforces the maximum user limit. + +**Example:** + +```json +{ + "settings": { + "max_allowed_users": 100 + } +} +``` + +### List organization users + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{organization_id}/users` +- **Tags:** Users + +Retrieves a paginated list of all users who are members of the specified organization. Use this endpoint to view all users with access to a particular organization, including their roles, metadata, and membership details. Supports pagination for large user lists. + +#### Responses + +##### Status: 200 Successfully retrieved the list of users in the organization + +###### Content-Type: application/json + +- **`next_page_token`** + + `string` — Opaque token for retrieving the next page of results. Empty if there are no more pages. + +- **`prev_page_token`** + + `string` — Opaque token for retrieving the previous page of results. Empty for the first page. + +- **`total_size`** + + `integer`, format: `int64` — Total number of users matching the request criteria, regardless of pagination. + +- **`users`** + + `array` — List of user objects for the current page. May contain fewer entries than requested page\_size. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "next_page_token": "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=", + "prev_page_token": "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9", + "total_size": 1042, + "users": [ + { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } + ] +} +``` + +### Create new user in organization + +- **Method:** `POST` +- **Path:** `/api/v1/organizations/{organization_id}/users` +- **Tags:** Users + +Creates a new user account and immediately adds them to the specified organization. Use this endpoint when you want to create a user and grant them access to an organization in a single operation. You can provide user profile information, assign roles, and configure membership metadata. The user receives an activation email unless this feature is disabled in the organization settings. + +#### Request Body + +##### Content-Type: application/json + +- **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + +- **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + +- **`membership`** + + `object` — List of organization memberships. Automatically populated based on group assignments. + + - **`inviter_email`** + + `string` — Email address of the user who invited this member. Must be a valid email address. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`roles`** + + `array` — Role to assign to the user within the organization + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + +- **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + +- **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data. Keys (3-25 chars), values (1-256 chars). + + - **`family_name`** + + `string` — User's family name. Maximum 255 characters. + + - **`gender`** + + `string` — User's gender identity. + + - **`given_name`** + + `string` — User's given name. Maximum 255 characters. + + - **`groups`** + + `array` — List of group names the user belongs to. Each group name must be 1-250 characters + + **Items:** + + `string` + + - **`locale`** + + `string` — User's localization preference in BCP-47 format. Defaults to organization settings. + + - **`metadata`** + + `object` — System-managed key-value pairs for internal tracking. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Full name in display format. Typically combines first\_name and last\_name. + + - **`phone_number`** + + `string` — Phone number in E.164 international format. Required for SMS-based authentication. + + - **`picture`** + + `string` — URL to the user's profile picture or avatar. + + - **`preferred_username`** + + `string` — User's preferred username for display purposes. + +**Example:** + +```json +{ + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "membership": { + "inviter_email": "john.doe@example.com", + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "roles": [ + { + "name": "admin" + } + ] + }, + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "user_profile": { + "custom_attributes": { + "department": "engineering", + "security_clearance": "level2" + }, + "family_name": "Doe", + "gender": "male", + "given_name": "John", + "groups": [ + "engineering", + "managers" + ], + "locale": "en-US", + "metadata": { + "account_status": "active", + "signup_source": "mobile_app" + }, + "name": "John Michael Doe", + "phone_number": "+14155552671", + "picture": "https://example.com/avatar.jpg", + "preferred_username": "John Michael Doe" + } +} +``` + +#### Responses + +##### Status: 201 User created successfully. Returns the created user object, including system-generated identifiers and timestamps + +###### Content-Type: application/json + +- **`user`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "user": { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } +} +``` + +### List user permissions + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{organization_id}/users/{user_id}/permissions` +- **Tags:** Users + +Retrieves all permissions a user has access to within a specific organization. This includes permissions from direct role assignments and inherited permissions from role hierarchy. + +#### Responses + +##### Status: 200 Successfully retrieved the list of permissions for the user + +###### Content-Type: application/json + +- **`permissions`** + + `array` — List of permissions the user has access to + + **Items:** + + - **`description`** + + `string` — Description of what the permission allows + + - **`id`** + + `string` — Unique identifier for the permission + + - **`name`** + + `string` — Unique name identifier for the permission + +**Example:** + +```json +{ + "permissions": [ + { + "description": "Allows creating new user accounts", + "id": "perm_1234abcd5678efgh", + "name": "users:create" + } + ] +} +``` + +### List user roles + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{organization_id}/users/{user_id}/roles` +- **Tags:** Users + +Retrieves all roles assigned to a user within a specific organization. This includes both direct role assignments and inherited roles from role hierarchy. + +#### Responses + +##### Status: 200 Successfully retrieved the list of roles assigned to the user + +###### Content-Type: application/json + +- **`roles`** + + `array` — List of roles assigned to the user + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + +**Example:** + +```json +{ + "roles": [ + { + "display_name": "Dev Team", + "id": "role_79643236410327240", + "name": "team_dev" + } + ] +} +``` + +### Search organization users + +- **Method:** `GET` +- **Path:** `/api/v1/organizations/{organization_id}/users:search` +- **Tags:** Users + +Searches for users within a specific organization by email address, user ID, or external ID. The query must be at least 3 characters and is case-insensitive. Scopes results strictly to the given organization. Returns a paginated list of matching users with up to 30 results per page. Use the next\_page\_token from the response to retrieve subsequent pages. + +#### Responses + +##### Status: 200 Matching users within the organization returned; includes pagination cursors for navigating large result sets. + +###### Content-Type: application/json + +- **`next_page_token`** + + `string` — Token for retrieving the next page of results. Empty if there are no more pages. + +- **`prev_page_token`** + + `string` — Token for retrieving the previous page of results. Empty if this is the first page. + +- **`total_size`** + + `integer`, format: `int64` — Total number of users matching the request criteria, regardless of pagination. + +- **`users`** + + `array` — List of matching users. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "next_page_token": "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=", + "prev_page_token": "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9", + "total_size": 1042, + "users": [ + { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } + ] +} +``` + +##### Status: 400 Bad Request - query must be at least 3 characters and no more than 100 characters, and organization\_id must be a valid org\_ prefixed identifier. + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 404 Not Found - organization not found. + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Get organization details by external Id + +- **Method:** `GET` +- **Path:** `/api/v1/organizations:external/{external_id}` +- **Tags:** Organizations + +Retrieves organization details by External ID, including name, region, metadata, and settings + +#### Responses + +##### Status: 200 Returns the complete organization object with ID, display name, settings, external ID and metadata + +###### Content-Type: application/json + +- **`organization`** + + `object` — The newly created organization + + - **`create_time` (required)** + + `string`, format: `date-time` — Timestamp when the organization was created + + - **`display_name`** + + `string` — Name of the organization. Must be between 1 and 200 characters + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique scalekit-generated identifier that uniquely references an organization + + - **`metadata`** + + `object` — Key value pairs extension attributes. + + - **`region_code`** + + `string`, possible values: `"US", "EU"` — Geographic region code for the organization. Currently limited to US. + + - **`settings`** + + `object` — Configuration options that control organization-level features and capabilities + + - **`features`** + + `array` — List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization + + **Items:** + + - **`enabled` (required)** + + `boolean` — Whether the feature is enabled (true) or disabled (false) for this organization + + - **`name` (required)** + + `string` — Feature identifier. Supported values include: "sso" (Single Sign-On), "directory\_sync" (Directory Synchronization), "domain\_verification" (Domain Verification) + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the organization was last updated + +**Example:** + +```json +{ + "organization": { + "create_time": "2025-02-15T06:23:44.560000Z", + "display_name": "Megasoft", + "external_id": "my_unique_id", + "id": "org_59615193906282635", + "metadata": { + "additionalProperty": "" + }, + "region_code": "US", + "settings": null, + "update_time": "2025-02-15T06:23:44.560000Z" + } +} +``` + +##### Status: 400 Invalid request - external ID is empty or the caller's organization claim does not match + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +##### Status: 404 Organization not found - no organization exists with the specified external ID + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Resend passwordless email + +- **Method:** `POST` +- **Path:** `/api/v1/passwordless/email/resend` +- **Tags:** Magic link & OTP + +Resend a verification email if the user didn't receive it or if the previous code/link has expired + +#### Request Body + +##### Content-Type: application/json + +- **`auth_request_id`** + + `string` — The authentication request identifier from the original send passwordless email request. Use this to resend the Verification Code (OTP) or Magic Link to the same email address. + +**Example:** + +```json +{ + "auth_request_id": "h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ" +} +``` + +#### Responses + +##### Status: 200 Successfully resent the passwordless authentication email. Returns updated authentication request details with new expiration time. + +###### Content-Type: application/json + +- **`auth_request_id`** + + `string` — Unique identifier for this passwordless authentication request. Use this ID to resend emails. + +- **`expires_at`** + + `string`, format: `int64` — Unix timestamp (seconds since epoch) when the passwordless authentication will expire. After this time, the OTP or magic link will no longer be valid. + +- **`expires_in`** + + `integer`, format: `int64` — Number of seconds from now until the passwordless authentication expires. This is a convenience field calculated from the expires\_at timestamp. + +- **`passwordless_type`** + + `string`, possible values: `"OTP", "LINK", "LINK_OTP"` — Type of passwordless authentication that was sent via email. OTP sends a numeric code, LINK sends a clickable magic link, and LINK\_OTP provides both options for user convenience. + +**Example:** + +```json +{ + "auth_request_id": "h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ", + "expires_at": 1748696575, + "expires_in": 300, + "passwordless_type": "OTP" +} +``` + +### Send passwordless email + +- **Method:** `POST` +- **Path:** `/api/v1/passwordless/email/send` +- **Tags:** Magic link & OTP + +Send a verification email containing either a verification code (OTP), magic link, or both to a user's email address + +#### Request Body + +##### Content-Type: application/json + +- **`email`** + + `string` — Email address where the passwordless authentication credentials will be sent. Must be a valid email format. + +- **`expires_in`** + + `integer`, format: `int64` — Time in seconds until the passwordless authentication expires. If not specified, defaults to 300 seconds (5 minutes) + +- **`magiclink_auth_uri`** + + `string` — Your application's callback URL where users will be redirected after clicking the magic link in their email. The link token will be appended as a query parameter as link\_token + +- **`state`** + + `string` — Custom state parameter that will be returned unchanged in the verification response. Use this to maintain application state between the authentication request and callback, such as the intended destination after login + +- **`template`** + + `string`, possible values: `"SIGNIN", "SIGNUP"` — Specifies the authentication intent for the passwordless request. Use SIGNIN for existing users or SIGNUP for new user registration. This affects the email template and user experience flow. + +- **`template_variables`** + + `object` — A set of key-value pairs to personalize the email template. \* You may include up to 30 key-value pairs. \* The following variable names are reserved by the system and cannot be supplied: \`otp\`, \`expiry\_time\_relative\`, \`link\`, \`expire\_time\`, \`expiry\_time\`. \* Every variable referenced in your email template must be included as a key-value pair. Use these variables to insert custom information, such as a team name, URL or the user's employee ID. All variables are interpolated before the email is sent, regardless of the email provider. + +**Example:** + +```json +{ + "email": "john.doe@example.com", + "expires_in": 300, + "magiclink_auth_uri": "https://yourapp.com/auth/passwordless/callback", + "state": "d62ivasry29lso", + "template": "SIGNIN", + "template_variables": { + "custom_variable_key": "custom_variable_value" + } +} +``` + +#### Responses + +##### Status: 200 Successfully sent passwordless authentication email. Returns the authentication request details including expiration time and auth request ID + +###### Content-Type: application/json + +- **`auth_request_id`** + + `string` — Unique identifier for this passwordless authentication request. Use this ID to resend emails. + +- **`expires_at`** + + `string`, format: `int64` — Unix timestamp (seconds since epoch) when the passwordless authentication will expire. After this time, the OTP or magic link will no longer be valid. + +- **`expires_in`** + + `integer`, format: `int64` — Number of seconds from now until the passwordless authentication expires. This is a convenience field calculated from the expires\_at timestamp. + +- **`passwordless_type`** + + `string`, possible values: `"OTP", "LINK", "LINK_OTP"` — Type of passwordless authentication that was sent via email. OTP sends a numeric code, LINK sends a clickable magic link, and LINK\_OTP provides both options for user convenience. + +**Example:** + +```json +{ + "auth_request_id": "h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ", + "expires_at": 1748696575, + "expires_in": 300, + "passwordless_type": "OTP" +} +``` + +### Verify passwordless email + +- **Method:** `POST` +- **Path:** `/api/v1/passwordless/email/verify` +- **Tags:** Magic link & OTP + +Verify a user's identity using either a verification code or magic link token + +#### Request Body + +##### Content-Type: application/json + +- **`auth_request_id`** + + `string` — The authentication request identifier returned from the send passwordless email endpoint. Required when verifying OTP codes to link the verification with the original request. + +- **`code`** + + `string` — The Verification Code (OTP) received via email. This is typically a 6-digit numeric code that users enter manually to verify their identity. + +- **`link_token`** + + `string` — The unique token from the magic link URL received via email. Extract this token when users click the magic link and are redirected to your application to later verify the user. + +**Example:** + +```json +{ + "auth_request_id": "h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ", + "code": "123456", + "link_token": "afe9d61c-d80d-4020-a8ee-61765ab71cb3" +} +``` + +#### Responses + +##### Status: 200 Successfully verified the passwordless authentication. Returns user email + +###### Content-Type: application/json + +- **`email`** + + `string` — Email address of the successfully authenticated user. This confirms which email account was verified through the passwordless flow. + +- **`passwordless_type`** + + `string`, possible values: `"OTP", "LINK", "LINK_OTP"` — The type of passwordless authentication that was successfully verified, confirming which method the user completed. + +- **`state`** + + `string` — The custom state parameter that was provided in the original authentication request, returned unchanged. Use this to restore your application's context after authentication. + +- **`template`** + + `string`, possible values: `"SIGNIN", "SIGNUP"` — Specifies which email template to choose. For User Signin choose SIGNIN and for User Signup use SIGNUP + +**Example:** + +```json +{ + "email": "john.doe@example.com", + "passwordless_type": "OTP", + "state": "kdt7yiag28t341fr1", + "template": "SIGNIN" +} +``` + +### List all permissions + +- **Method:** `GET` +- **Path:** `/api/v1/permissions` +- **Tags:** Permissions + +Retrieves a comprehensive, paginated list of all permissions available within the environment. Use this endpoint to view all permission definitions for auditing, role management, or understanding the complete set of available access controls. The response includes pagination tokens to navigate through large sets of permissions efficiently. Each permission object contains the permission name, description, creation time, and last update time. This operation is useful for building permission selection interfaces, auditing permission usage, or understanding the scope of available access controls in your RBAC system. + +#### Responses + +##### Status: 200 Successfully retrieved the list of permissions. Returns a paginated list of permission objects with metadata and pagination tokens for navigation. + +###### Content-Type: application/json + +- **`next_page_token`** + + `string` — Token to retrieve next page of results + +- **`permissions`** + + `array` + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`is_scalekit_permission`** + + `boolean` — Indicates whether this permission is predefined by Scalekit + + - **`name`** + + `string` + + - **`update_time`** + + `string`, format: `date-time` + +- **`prev_page_token`** + + `string` — Token to retrieve previous page of results + +- **`total_size`** + + `integer`, format: `int64` — Total number of permissions available + +**Example:** + +```json +{ + "next_page_token": "token_def456", + "permissions": [ + { + "create_time": "", + "description": "", + "id": "", + "is_scalekit_permission": true, + "name": "", + "update_time": "" + } + ], + "prev_page_token": "token_def456", + "total_size": 150 +} +``` + +### Create new permission + +- **Method:** `POST` +- **Path:** `/api/v1/permissions` +- **Tags:** Permissions + +Creates a new permission that represents a specific action users can perform within the environment. Use this endpoint to define granular access controls for your RBAC system. You can provide a unique permission name following the format 'action:resource' (for example, 'read:documents', 'write:users') and an optional description explaining the permission's purpose. The permission name must be unique across the environment and follows alphanumeric naming conventions with colons and underscores. Returns the created permission object including system-generated ID and timestamps. + +#### Request Body + +##### Content-Type: application/json + +- **`description`** + + `string` — Description of the permission + +- **`name`** + + `string` — Unique name/ID of the permission + +**Example:** + +```json +{ + "description": "Allows user to read documents from the system", + "name": "read:documents" +} +``` + +#### Responses + +##### Status: 201 Permission created successfully. Returns the complete permission object with system-generated ID, name, description, and timestamps. + +###### Content-Type: application/json + +- **`permission`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`is_scalekit_permission`** + + `boolean` — Indicates whether this permission is predefined by Scalekit + + - **`name`** + + `string` + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "permission": { + "create_time": "", + "description": "", + "id": "", + "is_scalekit_permission": true, + "name": "", + "update_time": "" + } +} +``` + +### Retrieve permission details + +- **Method:** `GET` +- **Path:** `/api/v1/permissions/{permission_name}` +- **Tags:** Permissions + +Retrieves complete information for a specific permission by its unique name identifier. Use this endpoint to view permission details including description, creation time, and last update time. Provide the permission name in the path parameter following the format 'action:resource' (for example, 'read:documents'). This operation is useful for auditing permission definitions, understanding permission purposes, or verifying permission existence before assignment. Returns the complete permission object with all metadata and system-generated timestamps. + +#### Responses + +##### Status: 200 Successfully retrieved permission details. Returns the complete permission object including name, description, creation time, and update time. + +###### Content-Type: application/json + +- **`permission`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`is_scalekit_permission`** + + `boolean` — Indicates whether this permission is predefined by Scalekit + + - **`name`** + + `string` + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "permission": { + "create_time": "", + "description": "", + "id": "", + "is_scalekit_permission": true, + "name": "", + "update_time": "" + } +} +``` + +### Update permission details + +- **Method:** `PUT` +- **Path:** `/api/v1/permissions/{permission_name}` +- **Tags:** Permissions + +Modifies an existing permission's attributes including description and metadata. Use this endpoint to update permission descriptions or clarify permission purposes after creation. The permission is identified by its unique name in the path parameter, and only the fields you specify in the request body will be updated. Note that the permission name itself cannot be changed as it serves as the immutable identifier. This operation is useful for maintaining clear documentation of permission purposes or updating descriptions to reflect changes in system functionality. Returns the updated permission object with modified timestamps. + +#### Request Body + +##### Content-Type: application/json + +- **`description`** + + `string` — Description of the permission + +- **`name`** + + `string` — Unique name/ID of the permission + +**Example:** + +```json +{ + "description": "Allows user to read documents from the system", + "name": "read:documents" +} +``` + +#### Responses + +##### Status: 200 Permission updated successfully. Returns the modified permission object with updated description and timestamps. + +###### Content-Type: application/json + +- **`permission`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`is_scalekit_permission`** + + `boolean` — Indicates whether this permission is predefined by Scalekit + + - **`name`** + + `string` + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "permission": { + "create_time": "", + "description": "", + "id": "", + "is_scalekit_permission": true, + "name": "", + "update_time": "" + } +} +``` + +### Delete permission + +- **Method:** `DELETE` +- **Path:** `/api/v1/permissions/{permission_name}` +- **Tags:** Permissions + +Permanently removes a permission from the environment using its unique name identifier. Use this endpoint when you need to clean up unused permissions or remove access controls that are no longer relevant. The permission is identified by its name in the path parameter following the format 'action:resource'. This operation cannot be undone, so ensure no active roles depend on the permission before deletion. If the permission is currently assigned to any roles, you may need to remove those assignments first or update the roles to use alternative permissions. Returns no content on successful deletion. + +#### Responses + +##### Status: 200 Permission successfully deleted. No content returned. + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### List all roles in environment + +- **Method:** `GET` +- **Path:** `/api/v1/roles` +- **Tags:** Roles + +Retrieves a comprehensive list of all roles available within the specified environment including organization roles. Use this endpoint to view all role definitions, including custom roles and their configurations. You can optionally include permission details for each role to understand their capabilities. This is useful for role management, auditing organization access controls, or understanding the available access levels within the organization. + +#### Responses + +##### Status: 200 Successfully retrieved list of roles. Returns all roles with their metadata and optionally their permissions. + +###### Content-Type: application/json + +- **`roles`** + + `array` — List of all roles in the environment with their metadata and optionally their permissions. + + **Items:** + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "roles": [ + { + "display_name": "Administrator", + "id": "role_1234abcd5678efgh", + "name": "admin" + }, + { + "display_name": "Viewer", + "id": "role_9876zyxw5432vuts", + "name": "viewer" + } + ] +} +``` + +### Create new role in environment + +- **Method:** `POST` +- **Path:** `/api/v1/roles` +- **Tags:** Roles + +Creates a new role within the environment with specified permissions and metadata. Use this endpoint to define custom roles that can be assigned to users or groups. You can create hierarchical roles by extending existing roles, assign specific permissions, and configure display information. Roles are the foundation of your access control system and determine what actions users can perform. + +#### Request Body + +##### Content-Type: application/json + +- **`description`** + + `string` — Detailed description of the role's purpose, capabilities, and intended use cases. Maximum 2000 characters. + +- **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces, reports, and user-facing communications. + +- **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance where this role inherits all permissions from the base role. + +- **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-64 characters. This name is used in API calls and cannot be changed after creation. + +- **`permissions`** + + `array` — List of permission names to assign to this role. Permissions must exist in the current environment. Maximum 100 permissions per role. + + **Items:** + + `string` + +**Example:** + +```json +{ + "description": "Can create, edit, and publish content but cannot delete content or manage user accounts", + "display_name": "Content Editor", + "extends": "viewer", + "name": "content_editor", + "permissions": [ + "read:content", + "write:content", + "publish:content" + ] +} +``` + +#### Responses + +##### Status: 201 Role created successfully. Returns the complete role object with system-generated ID and timestamps. + +###### Content-Type: application/json + +- **`role`** + + `object` — The created role object with system-generated ID and all configuration details. + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "role": { + "description": "Can edit content", + "display_name": "Content Editor", + "id": "role_1234abcd5678efgh", + "name": "content_editor" + } +} +``` + +### Set default creator and member roles + +- **Method:** `PATCH` +- **Path:** `/api/v1/roles/default` +- **Tags:** Roles + +Updates the default creator and member roles for the current environment. Use this endpoint to configure which roles are automatically assigned to new users when they join the environment. You can specify role names for both creator and member default roles. The system will validate that the specified roles exist and update the environment settings accordingly. Returns the updated default role objects including their complete role information and permissions. + +#### Request Body + +##### Content-Type: application/json + +- **`default_creator`** + + `object` — Default creator role (deprecated - use default\_creator\_role field instead) + + - **`id`** + + `string` + + - **`name`** + + `string` — Unique name of the role + +- **`default_creator_role`** + + `string` — Name of the role to set as the default creator role. This role will be automatically assigned to users who create new resources in the environment. Must be a valid role name that exists in the environment. + +- **`default_member`** + + `object` — Default member role (deprecated - use default\_member\_role field instead) + + - **`id`** + + `string` + + - **`name`** + + `string` — Unique name of the role + +- **`default_member_role`** + + `string` — Name of the role to set as the default member role. This role will be automatically assigned to new users when they join the environment. Must be a valid role name that exists in the environment. + +**Example:** + +```json +{ + "default_creator": { + "description": "Role for creating resources", + "display_name": "Creator Role", + "id": "role_1234567890", + "name": "creator" + }, + "default_creator_role": "creator", + "default_member": { + "description": "Role for regular members", + "display_name": "Member Role", + "id": "role_0987654321", + "name": "member" + }, + "default_member_role": "member" +} +``` + +#### Responses + +##### Status: 200 Default roles updated successfully + +###### Content-Type: application/json + +- **`default_creator`** + + `object` — The role that is now set as the default creator role for the environment. Contains complete role information including permissions and metadata. + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +- **`default_member`** + + `object` — The role that is now set as the default member role for the environment. Contains complete role information including permissions and metadata. + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "default_creator": { + "description": "Role for creating resources", + "display_name": "Creator Role", + "id": "role_1234567890", + "name": "creator" + }, + "default_member": { + "description": "Role for regular members", + "display_name": "Member Role", + "id": "role_0987654321", + "name": "member" + } +} +``` + +### Get role details + +- **Method:** `GET` +- **Path:** `/api/v1/roles/{role_name}` +- **Tags:** Roles + +Retrieves complete information for a specific role including metadata and inheritance details (base role and dependent role count). Use this endpoint to audit role configuration and understand the role's place in the hierarchy. To view the role's permissions, use the ListRolePermissions endpoint. + +#### Responses + +##### Status: 200 Successfully retrieved role details. Returns the role object including metadata and inheritance details. Permissions are not included. + +###### Content-Type: application/json + +- **`role`** + + `object` — The complete role object with all metadata, permissions, and inheritance details. + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "role": { + "dependent_roles_count": 2, + "display_name": "Content Editor", + "id": "role_1234abcd5678efgh", + "name": "content_editor", + "permissions": [ + { + "name": "read:content" + } + ] + } +} +``` + +### Update role information + +- **Method:** `PUT` +- **Path:** `/api/v1/roles/{role_name}` +- **Tags:** Roles + +Modifies an existing role's properties including display name, description, permissions, and inheritance. Use this endpoint to update role metadata, change permission assignments, or modify role hierarchy. Only the fields you specify will be updated, leaving other properties unchanged. When updating permissions, the new list replaces all existing permissions for the role. + +#### Request Body + +##### Content-Type: application/json + +- **`description`** + + `string` — Detailed description of the role's purpose, capabilities, and intended use cases. Maximum 2000 characters. + +- **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces, reports, and user-facing communications. + +- **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance where this role inherits all permissions from the base role. + +- **`permissions`** + + `array` — List of permission names to assign to this role. When provided, this replaces all existing role-permission mappings. Permissions must exist in the current environment. Maximum 100 permissions per role. + + **Items:** + + `string` + +**Example:** + +```json +{ + "description": "Can create, edit, publish, and approve content. Cannot delete content or manage user accounts.", + "display_name": "Senior Content Editor", + "extends": "content_editor", + "permissions": [ + "read:content", + "write:content", + "publish:content", + "approve:content" + ] +} +``` + +#### Responses + +##### Status: 200 Role updated successfully. Returns the modified role object with updated timestamps. + +###### Content-Type: application/json + +- **`role`** + + `object` — The updated role object with all current configuration details. + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "role": { + "description": "Can edit and approve content", + "display_name": "Senior Editor", + "id": "role_1234abcd5678efgh", + "name": "content_editor" + } +} +``` + +### Delete role and reassign users + +- **Method:** `DELETE` +- **Path:** `/api/v1/roles/{role_name}` +- **Tags:** Roles + +Permanently removes a role from the environment and reassigns users who had that role to a different role. Use this endpoint when you need to clean up unused roles or restructure your access control system. The role cannot be deleted if it has dependent roles (roles that extend it) unless you specify a replacement role. If users are assigned to the role being deleted, you must provide a reassign\_role\_name to move those users to a different role before deletion can proceed. This action cannot be undone, so ensure no critical users depend on the role before deletion. + +#### Responses + +##### Status: 200 Role successfully deleted and users reassigned. No content returned. + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Delete role inheritance relationship + +- **Method:** `DELETE` +- **Path:** `/api/v1/roles/{role_name}/base` +- **Tags:** Roles + +Removes the base role inheritance relationship for a specified role, effectively eliminating all inherited permissions from the base role. Use this endpoint when you want to break the hierarchical relationship between roles and remove inherited permissions. The role will retain only its directly assigned permissions after this operation. This action cannot be undone, so ensure the role has sufficient direct permissions before removing inheritance. Returns no content on successful removal of the base relationship. + +#### Responses + +##### Status: 200 Base role inheritance relationship successfully removed. The role now has only its directly assigned permissions. + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### List dependent roles + +- **Method:** `GET` +- **Path:** `/api/v1/roles/{role_name}/dependents` +- **Tags:** Roles + +Retrieves all roles that directly extend the specified base role through inheritance. Use this endpoint to understand the role hierarchy and identify which roles inherit permissions from a particular base role. Provide the base role name as a path parameter, and the response will include all dependent roles with their metadata and permission information. This operation is useful for auditing role inheritance relationships, understanding the impact of changes to base roles, or managing role hierarchies effectively. Returns a list of dependent role objects including their names, display names, descriptions, and permission details. + +#### Responses + +##### Status: 200 Successfully retrieved dependent roles. Returns a list of all roles that extend the specified base role, including their metadata and permission information. + +###### Content-Type: application/json + +- **`roles`** + + `array` — List of dependent roles + + **Items:** + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "roles": [ + { + "default_creator": true, + "default_member": true, + "dependent_roles_count": 3, + "description": "Can create, edit, and publish content but cannot delete or manage users", + "display_name": "Content Editor", + "extends": "admin_role", + "id": "role_1234abcd5678efgh", + "is_org_role": true, + "name": "content_editor", + "permissions": [ + { + "description": "Read Content", + "name": "read:content", + "role_name": "admin_role" + }, + { + "description": "Write Content", + "name": "write:content", + "role_name": "editor_role" + } + ] + } + ] +} +``` + +### List permissions for role + +- **Method:** `GET` +- **Path:** `/api/v1/roles/{role_name}/permissions` +- **Tags:** Roles + +Retrieves all permissions directly assigned to the specified role, excluding permissions inherited from base roles. Use this endpoint to view the explicit permission assignments for a role, which is useful for understanding direct role capabilities, auditing permission assignments, or managing role-permission relationships. Provide the role name as a path parameter, and the response will include only the permissions that are directly assigned to that role. This operation does not include inherited permissions from role hierarchies - use ListEffectiveRolePermissions to see the complete set of permissions including inheritance. Returns a list of permission objects with their names, descriptions, and assignment metadata. + +#### Responses + +##### Status: 200 Successfully retrieved role permissions. Returns a list of all permissions directly assigned to the specified role, excluding inherited permissions. + +###### Content-Type: application/json + +- **`permissions`** + + `array` — List of permissions directly assigned to the role + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`is_scalekit_permission`** + + `boolean` — Indicates whether this permission is predefined by Scalekit + + - **`name`** + + `string` + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "permissions": [ + { + "create_time": "", + "description": "", + "id": "", + "is_scalekit_permission": true, + "name": "", + "update_time": "" + } + ] +} +``` + +### Add permissions to role + +- **Method:** `POST` +- **Path:** `/api/v1/roles/{role_name}/permissions` +- **Tags:** Roles + +Adds one or more permissions to the specified role while preserving existing permission assignments. Use this endpoint to grant additional capabilities to a role without affecting its current permission set. Provide the role name as a path parameter and a list of permission names in the request body. The system will validate that all specified permissions exist in the environment and add them to the role. Existing permission assignments remain unchanged, making this operation safe for incremental permission management. This is useful for gradually expanding role capabilities or adding new permissions as your system evolves. Returns the updated list of all permissions now assigned to the role. + +#### Request Body + +##### Content-Type: application/json + +- **`permission_names`** + + `array` — List of permission names to add to the role + + **Items:** + + `string` + +**Example:** + +```json +{ + "permission_names": [ + "" + ] +} +``` + +#### Responses + +##### Status: 200 Permissions added to role successfully. Returns the complete list of all permissions now assigned to the role, including both existing and newly added permissions. + +###### Content-Type: application/json + +- **`permissions`** + + `array` — List of all permissions belonging to the role after addition + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`is_scalekit_permission`** + + `boolean` — Indicates whether this permission is predefined by Scalekit + + - **`name`** + + `string` + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "permissions": [ + { + "create_time": "", + "description": "", + "id": "", + "is_scalekit_permission": true, + "name": "", + "update_time": "" + } + ] +} +``` + +### Remove permission from role + +- **Method:** `DELETE` +- **Path:** `/api/v1/roles/{role_name}/permissions/{permission_name}` +- **Tags:** Roles + +Removes a specific permission from the specified role, revoking that capability from all users assigned to the role. Use this endpoint to restrict role capabilities or remove unnecessary permissions. Provide both the role name and permission name as path parameters. This operation only affects the direct permission assignment and does not impact permissions inherited from base roles. If the permission is inherited through role hierarchy, you may need to modify the base role instead. This is useful for fine-tuning role permissions, implementing least-privilege access controls, or removing deprecated permissions. Returns no content on successful removal. + +#### Responses + +##### Status: 200 Permission removed from role successfully. No content returned. + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### List effective permissions for role + +- **Method:** `GET` +- **Path:** `/api/v1/roles/{role_name}/permissions:all` +- **Tags:** Roles + +Retrieves the complete set of effective permissions for a role, including both directly assigned permissions and permissions inherited from base roles through the role hierarchy. Use this endpoint to understand the full scope of capabilities available to users assigned to a specific role. Provide the role name as a path parameter, and the response will include all permissions that apply to the role, accounting for inheritance relationships. This operation is essential for auditing role capabilities, understanding permission inheritance, or verifying the complete access scope before role assignment. Returns a comprehensive list of permission names representing the full set of effective permissions for the specified role. + +#### Responses + +##### Status: 200 Successfully retrieved effective permissions. Returns the complete list of all permissions that apply to the role, including both direct assignments and inherited permissions from base roles. + +###### Content-Type: application/json + +- **`permissions`** + + `array` — List of all effective permissions including those inherited from base roles + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`is_scalekit_permission`** + + `boolean` — Indicates whether this permission is predefined by Scalekit + + - **`name`** + + `string` + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "permissions": [ + { + "create_time": "", + "description": "", + "id": "", + "is_scalekit_permission": true, + "name": "", + "update_time": "" + } + ] +} +``` + +### Retrieve user count for role + +- **Method:** `GET` +- **Path:** `/api/v1/roles/{role_name}/users:count` +- **Tags:** Roles + +Retrieves the total number of users currently assigned to the specified role within the environment. Use this endpoint to monitor role usage, enforce user limits, or understand the scope of role assignments. Provide the role's unique name as a path parameter, and the response will include the current user count for that role. This operation is read-only and does not modify any data or user assignments. The count reflects all users who have the role either directly assigned or inherited through organization membership. This information is useful for capacity planning, security auditing, or understanding the impact of role changes across your user base. + +#### Responses + +##### Status: 200 Successfully retrieved user count for the specified role. Returns the total number of users currently assigned to the role, including both direct assignments and inherited assignments. + +###### Content-Type: application/json + +- **`count`** + + `string`, format: `int64` — Number of users associated with the role + +**Example:** + +```json +{ + "count": 10 +} +``` + +### Set default creator and member roles + +- **Method:** `PATCH` +- **Path:** `/api/v1/roles:set_defaults` +- **Tags:** Roles + +Updates the default creator and member roles for the current environment. Use this endpoint to configure which roles are automatically assigned to new users when they join the environment. You can specify role names for both creator and member default roles. The system will validate that the specified roles exist and update the environment settings accordingly. Returns the updated default role objects including their complete role information and permissions. + +#### Request Body + +##### Content-Type: application/json + +- **`default_creator`** + + `object` — Default creator role (deprecated - use default\_creator\_role field instead) + + - **`id`** + + `string` + + - **`name`** + + `string` — Unique name of the role + +- **`default_creator_role`** + + `string` — Name of the role to set as the default creator role. This role will be automatically assigned to users who create new resources in the environment. Must be a valid role name that exists in the environment. + +- **`default_member`** + + `object` — Default member role (deprecated - use default\_member\_role field instead) + + - **`id`** + + `string` + + - **`name`** + + `string` — Unique name of the role + +- **`default_member_role`** + + `string` — Name of the role to set as the default member role. This role will be automatically assigned to new users when they join the environment. Must be a valid role name that exists in the environment. + +**Example:** + +```json +{ + "default_creator": { + "description": "Role for creating resources", + "display_name": "Creator Role", + "id": "role_1234567890", + "name": "creator" + }, + "default_creator_role": "creator", + "default_member": { + "description": "Role for regular members", + "display_name": "Member Role", + "id": "role_0987654321", + "name": "member" + }, + "default_member_role": "member" +} +``` + +#### Responses + +##### Status: 200 Default roles updated successfully + +###### Content-Type: application/json + +- **`default_creator`** + + `object` — The role that is now set as the default creator role for the environment. Contains complete role information including permissions and metadata. + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +- **`default_member`** + + `object` — The role that is now set as the default member role for the environment. Contains complete role information including permissions and metadata. + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "default_creator": { + "description": "Role for creating resources", + "display_name": "Creator Role", + "id": "role_1234567890", + "name": "creator" + }, + "default_member": { + "description": "Role for regular members", + "display_name": "Member Role", + "id": "role_0987654321", + "name": "member" + } +} +``` + +### Get session details + +- **Method:** `GET` +- **Path:** `/api/v1/sessions/{session_id}` +- **Tags:** Sessions + +Retrieves comprehensive details for a specific user session including authentication status, device information, and expiration timelines. Use this endpoint to fetch current session metadata for security audits, session validation, or to display session information in user account management interfaces. Returns all session properties including the user ID, authenticated organizations, device details with browser/OS information, IP address and geolocation, and all relevant timestamps (creation, last activity, idle expiration, absolute expiration, and actual expiration if applicable). + +#### Responses + +##### Status: 200 Successfully retrieved session details + +###### Content-Type: application/json + +- **`absolute_expires_at`** + + `string`, format: `date-time` — Hard expiration timestamp for the session regardless of user activity. The session will be forcibly terminated at this time. This represents the maximum session lifetime from creation. + +- **`authenticated_clients`** + + `array` — Details of the authenticated clients for this session: client ID and organization context. + + **Items:** + + - **`client_id`** + + `string` — Unique identifier of the authenticated client application. + + - **`organization_id`** + + `string` — Active or last active Organization ID associated with the authenticated client. + +- **`authenticated_organizations`** + + `array` — List of organization IDs that have been authenticated for this user within the current session. Contains all organizations where the user has successfully completed SSO or authentication. + + **Items:** + + `string` + +- **`created_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was created. This is set once at session creation and remains constant throughout the session lifetime. + +- **`device`** + + `object` — Complete device metadata associated with this session including browser, operating system, device type, and geographic location based on IP address. + + - **`browser`** + + `string` — Browser name and family extracted from the user agent. Examples: Chrome, Safari, Firefox, Edge, Mobile Safari. + + - **`browser_version`** + + `string` — Version of the browser application. Represents the specific release version of the browser being used. + + - **`device_type`** + + `string` — Categorized device type classification. Possible values: 'desktop' (traditional computers), 'mobile' (smartphones and small tablets), 'tablet' (large tablets), 'other'. Useful for displaying session information by device category. + + - **`ip`** + + `string` — IP address of the device that initiated the session. This is the public-facing IP address used to connect to the application. Useful for security audits and geographic distribution analysis. + + - **`location`** + + `object` — Geographic location information derived from IP address geolocation. Includes country, region, city, and coordinates. Note: Based on IP location data and may not represent the user's exact physical location. + + - **`city`** + + `string` — City name where the session originated based on IP geolocation. Approximate location derived from IP address. + + - **`latitude`** + + `string` — Latitude coordinate of the estimated location. Decimal format (e.g., '37.7749'). Note: Represents IP geolocation center and may not be precise. + + - **`longitude`** + + `string` — Longitude coordinate of the estimated location. Decimal format (e.g., '-122.4194'). Note: Represents IP geolocation center and may not be precise. + + - **`region`** + + `string` — Geographic region name derived from IP geolocation. Represents the country-level location (e.g., 'United States', 'France'). + + - **`region_subdivision`** + + `string` — Regional subdivision code or name (e.g., state abbreviation for US, province for Canada). Two-letter ISO format when applicable. + + - **`os`** + + `string` — Operating system name extracted from the user agent and device headers. Examples: macOS, Windows, Linux, iOS, Android. + + - **`os_version`** + + `string` — Version of the operating system. Represents the specific OS release the device is running. + + - **`user_agent`** + + `string` — Complete HTTP User-Agent header string from the client request. Contains browser type, version, and operating system information. Used for detailed device fingerprinting and user agent analysis. + +- **`expired_at`** + + `string`, format: `date-time` — Timestamp when the session was terminated. Null if the session is still active. Set when the session expires due to reaching idle\_expires\_at or absolute\_expires\_at timeout, or when administratively revoked. Not set for user-initiated logout (see logout\_at instead). + +- **`idle_expires_at`** + + `string`, format: `date-time` — Projected expiration timestamp if the session remains idle without user activity. This timestamp is recalculated with each user activity. Session will be automatically terminated at this time if no activity occurs. + +- **`last_active_at`** + + `string`, format: `date-time` — Timestamp of the most recent user activity detected in this session. Updated on each API request or user interaction. Used to determine if a session has exceeded the idle timeout threshold. + +- **`logout_at`** + + `string`, format: `date-time` — Timestamp when the user explicitly logged out from the session. Null if the user has not logged out. When set, indicates the session ended due to explicit user logout rather than timeout. + +- **`organization_id`** + + `string` — Organization ID for the user's most recently active organization within this session. This represents the primary organization context for the current session. + +- **`session_id`** + + `string` — Unique identifier for the session. System-generated read-only field used to reference this session. + +- **`status`** + + `string` — Current operational status of the session. Possible values: 'active' (session is valid and requests are allowed), 'expired' (session terminated due to idle or absolute timeout), 'revoked' (session was administratively revoked), 'logout' (user explicitly logged out). Use this to determine if the session can be used for new requests. + +- **`updated_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was last updated. Updated whenever session state changes such as organization context changes or metadata updates. + +- **`user_id`** + + `string` — Unique identifier for the user who owns and is authenticated within this session. + +**Example:** + +```json +{ + "absolute_expires_at": "2025-01-22T10:30:00Z", + "authenticated_clients": [ + { + "client_id": "skc_1234567890", + "organization_id": "org_1234567890" + } + ], + "authenticated_organizations": [ + "org_123", + "org_456" + ], + "created_at": "2025-01-15T10:30:00Z", + "device": { + "browser": "Chrome", + "browser_version": "120.0.0.0", + "device_type": "desktop", + "ip": "192.0.2.1", + "location": null, + "os": "macOS", + "os_version": "14.2", + "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" + }, + "expired_at": "2025-01-15T12:00:00Z", + "idle_expires_at": "2025-01-15T11:30:00Z", + "last_active_at": "2025-01-15T10:55:30Z", + "logout_at": "2025-01-15T14:00:00Z", + "organization_id": "org_1234567890123456", + "session_id": "ses_1234567890123456", + "status": "active", + "updated_at": "2025-01-15T10:45:00Z", + "user_id": "usr_1234567890123456" +} +``` + +### Revoke user session + +- **Method:** `POST` +- **Path:** `/api/v1/sessions/{session_id}/revoke` +- **Tags:** Sessions + +Immediately invalidates a specific user session by session ID, setting its status to 'revoked'. Once revoked, the session cannot be used for any future API requests or application access. Use this endpoint to implement session-level logout, force a user to reauthenticate on a specific device, or terminate suspicious sessions. The revocation is instantaneous and irreversible. Returns the revoked session details including the session ID, user ID, and the revocation timestamp. + +#### Responses + +##### Status: 200 Successfully revoked the session. Returns the revoked session details + +###### Content-Type: application/json + +- **`revoked_session`** + + `object` — Details of the revoked session including session ID, user ID, creation and revocation timestamps, and final device information. + + - **`absolute_expires_at`** + + `string`, format: `date-time` — The absolute expiration timestamp that was configured for this session before revocation. Represents the hard deadline regardless of activity. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was originally created before revocation. + + - **`expired_at`** + + `string`, format: `date-time` — Timestamp when the session was actually terminated. Set to the revocation time when the session is revoked. + + - **`idle_expires_at`** + + `string`, format: `date-time` — The idle expiration timestamp that was configured for this session before revocation. Represents when the session would have expired due to inactivity. + + - **`last_active_at`** + + `string`, format: `date-time` — Timestamp of the last recorded user activity in this session before revocation. Helps identify inactive sessions that were revoked. + + - **`logout_at`** + + `string`, format: `date-time` — Timestamp when the user explicitly logged out (if applicable). Null if the session was revoked without prior logout. + + - **`session_id`** + + `string` — Unique identifier for the revoked session. System-generated read-only field. + + - **`status`** + + `string` — Status of the session after revocation. Always 'revoked' since only active sessions can be revoked. Sessions that were already expired or logged out are not included in the revocation response. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was last modified before revocation. + + - **`user_id`** + + `string` — Unique identifier for the user who owned this session. + +**Example:** + +```json +{ + "revoked_session": { + "absolute_expires_at": "2025-01-22T10:30:00Z", + "created_at": "2025-01-15T10:30:00Z", + "expired_at": "2025-01-15T12:00:00Z", + "idle_expires_at": "2025-01-15T11:30:00Z", + "last_active_at": "2025-01-15T10:55:30Z", + "logout_at": "2025-01-15T14:00:00Z", + "session_id": "ses_1234567890123456", + "status": "revoked", + "updated_at": "2025-01-15T10:45:00Z", + "user_id": "usr_1234567890123456" + } +} +``` + +### List all users in environment + +- **Method:** `GET` +- **Path:** `/api/v1/users` +- **Tags:** Users + +Retrieves a paginated list of all users across your entire environment. Use this endpoint to view all users regardless of their organization memberships. This is useful for administrative purposes, user audits, or when you need to see all users in your Scalekit environment. Supports pagination for large user bases. + +#### Responses + +##### Status: 200 List of users. + +###### Content-Type: application/json + +- **`next_page_token`** + + `string` — Token for retrieving the next page of results. Empty if there are no more pages. + +- **`prev_page_token`** + + `string` — Token for retrieving the previous page of results. Empty if this is the first page. + +- **`total_size`** + + `integer`, format: `int64` — Total number of users matching the request criteria, regardless of pagination. + +- **`users`** + + `array` — List of users. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "next_page_token": "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=", + "prev_page_token": "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9", + "total_size": 1042, + "users": [ + { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } + ] +} +``` + +### Get user + +- **Method:** `GET` +- **Path:** `/api/v1/users/{id}` +- **Tags:** Users + +Retrieves all details for a user by system-generated user ID or external ID. The response includes organization memberships and user metadata. + +#### Responses + +##### Status: 200 User details retrieved successfully. Returns full user object with system-generated fields and timestamps. + +###### Content-Type: application/json + +- **`user`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "user": { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } +} +``` + +### Delete user permanently + +- **Method:** `DELETE` +- **Path:** `/api/v1/users/{id}` +- **Tags:** Users + +Permanently removes a user from your environment and deletes all associated data. Use this endpoint when you need to completely remove a user account. This action deletes the user's profile, memberships, and all related data across all organizations. This operation cannot be undone, so use with caution. + +#### Responses + +##### Status: 200 User successfully deleted. No content returned + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### Update user information + +- **Method:** `PATCH` +- **Path:** `/api/v1/users/{id}` +- **Tags:** Users + +Modifies user account information including profile details, metadata, and external ID. Use this endpoint to update a user's personal information, contact details, or custom metadata. You can update the user's profile, phone number, and metadata fields. Note that fields like user ID, email address, environment ID, and creation time cannot be modified. + +#### Request Body + +##### Content-Type: application/json + +- **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + +- **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + +- **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Updates custom attributes for extended user profile data and application-specific information. Use this field to store business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`family_name`** + + `string` — Updates the user's family name (last name or surname). Use this field to modify how the user's last name appears throughout the system. Maximum 255 characters allowed. + + - **`first_name`** + + `string` — \[DEPRECATED] Use given\_name instead. User's given name. Maximum 200 characters. + + - **`gender`** + + `string` — Updates the user's gender identity information. Use this field to store the user's gender identity for personalization, compliance, or reporting purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies. + + - **`given_name`** + + `string` — Updates the user's given name (first name). Use this field to modify how the user's first name appears in the system and user interfaces. Maximum 255 characters allowed. + + - **`groups`** + + `array` — Updates the list of group names the user belongs to within the organization. Use this field to manage the user's group memberships for role-based access control, team assignments, or organizational structure. Groups are typically used for permission management and collaborative access. Each group name must be unique within the list, 1-250 characters long, with a maximum of 50 groups per user. + + **Items:** + + `string` + + - **`last_name`** + + `string` — \[DEPRECATED] Use family\_name instead. User's family name. Maximum 200 characters. + + - **`locale`** + + `string` — Updates the user's preferred language and region settings using BCP-47 format codes. Use this field to customize the user's experience with localized content, date formats, number formatting, and UI language. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Updates system-managed key-value pairs for internal tracking and operational data. Use this field to store system-generated metadata like account status, signup source, last activity tracking, or integration-specific identifiers. These fields are typically managed by automated processes rather than direct user input. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — Updates the user's complete display name. Use this field when you want to set the full name as a single string rather than using separate given and family names. This name appears in user interfaces, reports, and anywhere a formatted display name is needed. + + - **`phone_number`** + + `string` — Updates the user's phone number in E.164 international format. Use this field to enable SMS-based authentication methods, two-factor authentication, or phone-based account recovery. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is required when enabling SMS authentication features. + + - **`picture`** + + `string` — Updates the URL to the user's profile picture or avatar image. Use this field to set or change the user's profile photo that appears in user interfaces, directory listings, and collaborative features. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. Maximum URL length is 2048 characters. + + - **`preferred_username`** + + `string` — Updates the user's preferred username for display and identification purposes. Use this field to set a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, and informal communications. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "external_id": "ext_12345a67b89c", + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "user_profile": { + "custom_attributes": { + "department": "engineering", + "security_clearance": "level2" + }, + "family_name": "Doe", + "first_name": "John", + "gender": "male", + "given_name": "John", + "groups": [ + "engineering", + "managers" + ], + "last_name": "Doe", + "locale": "en-US", + "metadata": { + "account_status": "active", + "signup_source": "mobile_app" + }, + "name": "John Doe", + "phone_number": "+14155552671", + "picture": "https://example.com/avatar.jpg", + "preferred_username": "John Michael Doe" + } +} +``` + +#### Responses + +##### Status: 200 User updated successfully. Returns the modified user object with updated timestamps. + +###### Content-Type: application/json + +- **`user`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "user": { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } +} +``` + +### List user sessions + +- **Method:** `GET` +- **Path:** `/api/v1/users/{user_id}/sessions` +- **Tags:** Sessions + +Retrieves a paginated list of all sessions associated with a specific user across all devices and browsers. Use this endpoint to audit user activity, display all active sessions in account management interfaces, or verify user authentication status across devices. Supports filtering by session status (active, expired, revoked, logout) and time range (creation date). Returns session details for each session including device information, IP address, geolocation, and current status. The response includes pagination metadata (page tokens and total count) to handle large session lists efficiently. + +#### Responses + +##### Status: 200 Successfully retrieved user sessions. Returns a list of sessions with pagination information + +###### Content-Type: application/json + +- **`next_page_token`** + + `string` — Pagination token for retrieving the next page of results. Empty string if there are no more pages (you have reached the final page of results). + +- **`prev_page_token`** + + `string` — Pagination token for retrieving the previous page of results. Empty string for the first page. Use this to navigate backward through result pages. + +- **`sessions`** + + `array` — Array of session objects for the requested user. May contain fewer entries than the requested page\_size when reaching the final page of results. + + **Items:** + + - **`absolute_expires_at`** + + `string`, format: `date-time` — Hard expiration timestamp for the session regardless of user activity. The session will be forcibly terminated at this time. This represents the maximum session lifetime from creation. + + - **`authenticated_clients`** + + `array` — Details of the authenticated clients for this session: client ID and organization context. + + **Items:** + + - **`client_id`** + + `string` — Unique identifier of the authenticated client application. + + - **`organization_id`** + + `string` — Active or last active Organization ID associated with the authenticated client. + + - **`authenticated_organizations`** + + `array` — List of organization IDs that have been authenticated for this user within the current session. Contains all organizations where the user has successfully completed SSO or authentication. + + **Items:** + + `string` + + - **`created_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was created. This is set once at session creation and remains constant throughout the session lifetime. + + - **`device`** + + `object` — Complete device metadata associated with this session including browser, operating system, device type, and geographic location based on IP address. + + - **`browser`** + + `string` — Browser name and family extracted from the user agent. Examples: Chrome, Safari, Firefox, Edge, Mobile Safari. + + - **`browser_version`** + + `string` — Version of the browser application. Represents the specific release version of the browser being used. + + - **`device_type`** + + `string` — Categorized device type classification. Possible values: 'desktop' (traditional computers), 'mobile' (smartphones and small tablets), 'tablet' (large tablets), 'other'. Useful for displaying session information by device category. + + - **`ip`** + + `string` — IP address of the device that initiated the session. This is the public-facing IP address used to connect to the application. Useful for security audits and geographic distribution analysis. + + - **`location`** + + `object` — Geographic location information derived from IP address geolocation. Includes country, region, city, and coordinates. Note: Based on IP location data and may not represent the user's exact physical location. + + - **`city`** + + `string` — City name where the session originated based on IP geolocation. Approximate location derived from IP address. + + - **`latitude`** + + `string` — Latitude coordinate of the estimated location. Decimal format (e.g., '37.7749'). Note: Represents IP geolocation center and may not be precise. + + - **`longitude`** + + `string` — Longitude coordinate of the estimated location. Decimal format (e.g., '-122.4194'). Note: Represents IP geolocation center and may not be precise. + + - **`region`** + + `string` — Geographic region name derived from IP geolocation. Represents the country-level location (e.g., 'United States', 'France'). + + - **`region_subdivision`** + + `string` — Regional subdivision code or name (e.g., state abbreviation for US, province for Canada). Two-letter ISO format when applicable. + + - **`os`** + + `string` — Operating system name extracted from the user agent and device headers. Examples: macOS, Windows, Linux, iOS, Android. + + - **`os_version`** + + `string` — Version of the operating system. Represents the specific OS release the device is running. + + - **`user_agent`** + + `string` — Complete HTTP User-Agent header string from the client request. Contains browser type, version, and operating system information. Used for detailed device fingerprinting and user agent analysis. + + - **`expired_at`** + + `string`, format: `date-time` — Timestamp when the session was terminated. Null if the session is still active. Set when the session expires due to reaching idle\_expires\_at or absolute\_expires\_at timeout, or when administratively revoked. Not set for user-initiated logout (see logout\_at instead). + + - **`idle_expires_at`** + + `string`, format: `date-time` — Projected expiration timestamp if the session remains idle without user activity. This timestamp is recalculated with each user activity. Session will be automatically terminated at this time if no activity occurs. + + - **`last_active_at`** + + `string`, format: `date-time` — Timestamp of the most recent user activity detected in this session. Updated on each API request or user interaction. Used to determine if a session has exceeded the idle timeout threshold. + + - **`logout_at`** + + `string`, format: `date-time` — Timestamp when the user explicitly logged out from the session. Null if the user has not logged out. When set, indicates the session ended due to explicit user logout rather than timeout. + + - **`organization_id`** + + `string` — Organization ID for the user's most recently active organization within this session. This represents the primary organization context for the current session. + + - **`session_id`** + + `string` — Unique identifier for the session. System-generated read-only field used to reference this session. + + - **`status`** + + `string` — Current operational status of the session. Possible values: 'active' (session is valid and requests are allowed), 'expired' (session terminated due to idle or absolute timeout), 'revoked' (session was administratively revoked), 'logout' (user explicitly logged out). Use this to determine if the session can be used for new requests. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was last updated. Updated whenever session state changes such as organization context changes or metadata updates. + + - **`user_id`** + + `string` — Unique identifier for the user who owns and is authenticated within this session. + +- **`total_size`** + + `integer`, format: `int64` — Total number of sessions matching the applied filter criteria, regardless of pagination. This represents the complete result set size before pagination is applied. + +**Example:** + +```json +{ + "next_page_token": "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAic2VzXzEyMzQ1In0=", + "prev_page_token": "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInNlc183OTAxIn0=", + "sessions": [ + { + "absolute_expires_at": "2025-01-22T10:30:00Z", + "authenticated_clients": [ + {} + ], + "authenticated_organizations": [ + "org_123", + "org_456" + ], + "created_at": "2025-01-15T10:30:00Z", + "device": null, + "expired_at": "2025-01-15T12:00:00Z", + "idle_expires_at": "2025-01-15T11:30:00Z", + "last_active_at": "2025-01-15T10:55:30Z", + "logout_at": "2025-01-15T14:00:00Z", + "organization_id": "org_1234567890123456", + "session_id": "ses_1234567890123456", + "status": "active", + "updated_at": "2025-01-15T10:45:00Z", + "user_id": "usr_1234567890123456" + } + ], + "total_size": 42 +} +``` + +### Revoke all user sessions + +- **Method:** `POST` +- **Path:** `/api/v1/users/{user_id}/sessions/revoke` +- **Tags:** Sessions + +Immediately invalidates all active sessions for a specific user across all devices and browsers, setting their status to 'revoked'. Use this endpoint to implement global logout functionality, force re-authentication after security incidents, or terminate all sessions following a password reset or credential compromise. Only active sessions are revoked; already expired, logout, or previously revoked sessions remain unchanged. The revocation is atomic and instantaneous. Returns a list of all revoked sessions with their details and a total count of sessions revoked. + +#### Responses + +##### Status: 200 Successfully revoked all user sessions. Returns the list of revoked sessions and total count + +###### Content-Type: application/json + +- **`revoked_sessions`** + + `array` — List of all sessions that were revoked, including detailed information for each revoked session with IDs, timestamps, and device details. + + **Items:** + + - **`absolute_expires_at`** + + `string`, format: `date-time` — The absolute expiration timestamp that was configured for this session before revocation. Represents the hard deadline regardless of activity. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was originally created before revocation. + + - **`expired_at`** + + `string`, format: `date-time` — Timestamp when the session was actually terminated. Set to the revocation time when the session is revoked. + + - **`idle_expires_at`** + + `string`, format: `date-time` — The idle expiration timestamp that was configured for this session before revocation. Represents when the session would have expired due to inactivity. + + - **`last_active_at`** + + `string`, format: `date-time` — Timestamp of the last recorded user activity in this session before revocation. Helps identify inactive sessions that were revoked. + + - **`logout_at`** + + `string`, format: `date-time` — Timestamp when the user explicitly logged out (if applicable). Null if the session was revoked without prior logout. + + - **`session_id`** + + `string` — Unique identifier for the revoked session. System-generated read-only field. + + - **`status`** + + `string` — Status of the session after revocation. Always 'revoked' since only active sessions can be revoked. Sessions that were already expired or logged out are not included in the revocation response. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was last modified before revocation. + + - **`user_id`** + + `string` — Unique identifier for the user who owned this session. + +- **`total_revoked`** + + `integer`, format: `int64` — Total count of active sessions that were revoked. Useful for confirmation and audit logging. + +**Example:** + +```json +{ + "revoked_sessions": [ + { + "absolute_expires_at": "2025-01-22T10:30:00Z", + "created_at": "2025-01-15T10:30:00Z", + "expired_at": "2025-01-15T12:00:00Z", + "idle_expires_at": "2025-01-15T11:30:00Z", + "last_active_at": "2025-01-15T10:55:30Z", + "logout_at": "2025-01-15T14:00:00Z", + "session_id": "ses_1234567890123456", + "status": "revoked", + "updated_at": "2025-01-15T10:45:00Z", + "user_id": "usr_1234567890123456" + } + ], + "total_revoked": 5 +} +``` + +### Search users + +- **Method:** `GET` +- **Path:** `/api/v1/users:search` +- **Tags:** Users + +Searches for users across the entire environment by email address, user ID, or external ID. The query must be at least 3 characters and is case-insensitive. Returns a paginated list of matching users with up to 30 results per page. Use the next\_page\_token from the response to retrieve subsequent pages. + +#### Responses + +##### Status: 200 Matching users returned; includes pagination cursors for navigating large result sets. + +###### Content-Type: application/json + +- **`next_page_token`** + + `string` — Token for retrieving the next page of results. Empty if there are no more pages. + +- **`prev_page_token`** + + `string` — Token for retrieving the previous page of results. Empty if this is the first page. + +- **`total_size`** + + `integer`, format: `int64` — Total number of users matching the request criteria, regardless of pagination. + +- **`users`** + + `array` — List of matching users. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "next_page_token": "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=", + "prev_page_token": "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9", + "total_size": 1042, + "users": [ + { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } + ] +} +``` + +##### Status: 400 Bad Request - query must be at least 3 characters and no more than 100 characters. + +###### Content-Type: application/json + +**Example:** + +```json +null +``` + +### List user's passkeys + +- **Method:** `GET` +- **Path:** `/api/v1/webauthn/credentials` +- **Tags:** Passkeys + +Retrieves all registered passkeys for the current user, including device information, creation timestamps, and display names. Use this to show users their registered authenticators. + +#### Responses + +##### Status: 200 List of passkeys with metadata + +###### Content-Type: application/json + +- **`all_accepted_credentials_options`** + + `object` — Options including RP ID and all accepted credential IDs for authentication + + - **`all_accepted_credential_ids`** + + `array` — List of credential IDs the user can authenticate with + + **Items:** + + `string` + + - **`rp_id`** + + `string` — Relying Party ID for credential operations + + - **`user_id`** + + `string` — User ID for credential verification + +- **`credentials`** + + `array` — All passkeys registered for the user + + **Items:** + + - **`attestation_type`** + + `string` — Type of attestation: "none", "indirect", or "direct" + + - **`authenticator`** + + `object` — Authenticator information including model and name + + - **`aaguid`** + + `string` — Authenticator Attestation GUID (AAGUID) identifying the device model + + - **`attachment`** + + `string` — Attachment type: "platform" (built-in) or "cross-platform" + + - **`icon_dark`** + + `string` — Icon URL for dark theme display + + - **`icon_light`** + + `string` — Icon URL for light theme display + + - **`name`** + + `string` — Human-readable name of the authenticator model + + - **`authenticator_flags`** + + `object` — Flags indicating authenticator capabilities + + - **`backup_eligible`** + + `boolean` — Whether this credential can be backed up to another device + + - **`backup_state`** + + `boolean` — Whether this credential was synced or backed up + + - **`user_present`** + + `boolean` — Whether the user was present during authentication + + - **`user_verified`** + + `boolean` — Whether the user was verified (e.g., fingerprint, PIN) + + - **`client_info`** + + `object` — Geographic and network information from registration + + - **`city`** + + `string` — City name + + - **`ip`** + + `string` — IP address from which credential was registered + + - **`region`** + + `string` — Geographic region (e.g., "US") + + - **`region_subdivision`** + + `string` — Regional subdivision (e.g., "CA") + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the credential was created + + - **`credential_id`** + + `string` — The actual credential ID bytes from the authenticator + + - **`display_name`** + + `string` — Optional user-friendly name for this passkey + + - **`id`** + + `string` — Credential unique identifier + + - **`transports`** + + `array` — Supported transports for this credential + + **Items:** + + `string` + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp of last update + + - **`user_agent`** + + `object` — Browser and device information from registration + + - **`browser`** + + `string` — Browser name (e.g., "Chrome", "Safari") + + - **`browser_version`** + + `string` — Browser version number + + - **`device_model`** + + `string` — Device model if available + + - **`device_type`** + + `string` — Device type: "desktop", "mobile", or "tablet" + + - **`os`** + + `string` — Operating system name (e.g., "Windows", "iOS") + + - **`os_version`** + + `string` — Operating system version + + - **`raw`** + + `string` — Raw user agent string from the browser + + - **`url`** + + `string` — Parsed user agent URL reference + + - **`user_id`** + + `string` — User ID this credential belongs to + +**Example:** + +```json +{ + "all_accepted_credentials_options": { + "all_accepted_credential_ids": [ + "" + ], + "rp_id": "example.com", + "user_id": "user_xyz789" + }, + "credentials": [ + { + "attestation_type": "direct", + "authenticator": null, + "authenticator_flags": null, + "client_info": null, + "created_at": "2025-02-15T06:23:44.560000Z", + "credential_id": "", + "display_name": "My Yubikey", + "id": "cred_abc123", + "transports": [ + "" + ], + "updated_at": "2025-02-15T06:23:44.560000Z", + "user_agent": null, + "user_id": "user_xyz789" + } + ] +} +``` + +### Remove a passkey + +- **Method:** `DELETE` +- **Path:** `/api/v1/webauthn/credentials/{credential_id}` +- **Tags:** Passkeys + +Deletes a specific passkey credential for the current user. After removal, the authenticator can no longer be used for authentication. + +#### Responses + +##### Status: 200 Passkey successfully deleted + +###### Content-Type: application/json + +- **`success`** + + `boolean` — Whether the credential was successfully deleted + +- **`unknown_credential_options`** + + `object` — Options for handling unknown credentials in client applications + + - **`credential_id`** + + `string` — The deleted credential ID + + - **`rp_id`** + + `string` — The RP ID for this credential + +**Example:** + +```json +{ + "success": true, + "unknown_credential_options": { + "credential_id": "cred_abc123", + "rp_id": "example.com" + } +} +``` + +### Rename a passkey + +- **Method:** `PATCH` +- **Path:** `/api/v1/webauthn/credentials/{credential_id}` +- **Tags:** Passkeys + +Updates the display name of a passkey credential to help users identify their authenticators. Only the display name can be modified. + +#### Request Body + +##### Content-Type: application/json + +- **`display_name`** + + `string` — Human-friendly name for this credential (1-120 characters) + +**Example:** + +```json +{ + "display_name": "My iPhone 15 Pro" +} +``` + +#### Responses + +##### Status: 200 Passkey successfully updated with new name + +###### Content-Type: application/json + +- **`credential`** + + `object` — The updated credential with new display name + + - **`attestation_type`** + + `string` — Type of attestation: "none", "indirect", or "direct" + + - **`authenticator`** + + `object` — Authenticator information including model and name + + - **`aaguid`** + + `string` — Authenticator Attestation GUID (AAGUID) identifying the device model + + - **`attachment`** + + `string` — Attachment type: "platform" (built-in) or "cross-platform" + + - **`icon_dark`** + + `string` — Icon URL for dark theme display + + - **`icon_light`** + + `string` — Icon URL for light theme display + + - **`name`** + + `string` — Human-readable name of the authenticator model + + - **`authenticator_flags`** + + `object` — Flags indicating authenticator capabilities + + - **`backup_eligible`** + + `boolean` — Whether this credential can be backed up to another device + + - **`backup_state`** + + `boolean` — Whether this credential was synced or backed up + + - **`user_present`** + + `boolean` — Whether the user was present during authentication + + - **`user_verified`** + + `boolean` — Whether the user was verified (e.g., fingerprint, PIN) + + - **`client_info`** + + `object` — Geographic and network information from registration + + - **`city`** + + `string` — City name + + - **`ip`** + + `string` — IP address from which credential was registered + + - **`region`** + + `string` — Geographic region (e.g., "US") + + - **`region_subdivision`** + + `string` — Regional subdivision (e.g., "CA") + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the credential was created + + - **`credential_id`** + + `string` — The actual credential ID bytes from the authenticator + + - **`display_name`** + + `string` — Optional user-friendly name for this passkey + + - **`id`** + + `string` — Credential unique identifier + + - **`transports`** + + `array` — Supported transports for this credential + + **Items:** + + `string` + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp of last update + + - **`user_agent`** + + `object` — Browser and device information from registration + + - **`browser`** + + `string` — Browser name (e.g., "Chrome", "Safari") + + - **`browser_version`** + + `string` — Browser version number + + - **`device_model`** + + `string` — Device model if available + + - **`device_type`** + + `string` — Device type: "desktop", "mobile", or "tablet" + + - **`os`** + + `string` — Operating system name (e.g., "Windows", "iOS") + + - **`os_version`** + + `string` — Operating system version + + - **`raw`** + + `string` — Raw user agent string from the browser + + - **`url`** + + `string` — Parsed user agent URL reference + + - **`user_id`** + + `string` — User ID this credential belongs to + +**Example:** + +```json +{ + "credential": { + "attestation_type": "direct", + "authenticator": null, + "authenticator_flags": null, + "client_info": null, + "created_at": "2025-02-15T06:23:44.560000Z", + "credential_id": "", + "display_name": "My Yubikey", + "id": "cred_abc123", + "transports": [ + "" + ], + "updated_at": "2025-02-15T06:23:44.560000Z", + "user_agent": null, + "user_id": "user_xyz789" + } +} +``` + +## Webhooks + +### Organization Created + +- **Method:**`POST` +- **Path:**`/webhooks/organization.created` + +Triggered when a new organization is created in Scalekit + +### Organization Updated + +- **Method:**`POST` +- **Path:**`/webhooks/organization.updated` + +Triggered when an organization is updated + +### Organization Deleted + +- **Method:**`POST` +- **Path:**`/webhooks/organization.deleted` + +Triggered when an organization is deleted + +### User Signup + +- **Method:**`POST` +- **Path:**`/webhooks/user.signup` + +Triggered when a user signs up to create a new organization + +### User Login + +- **Method:**`POST` +- **Path:**`/webhooks/user.login` + +Triggered when a user logs in and a session is created + +### User Logout + +- **Method:**`POST` +- **Path:**`/webhooks/user.logout` + +Triggered when a user's session is terminated + +### User Organization Invitation + +- **Method:**`POST` +- **Path:**`/webhooks/user.organization_invitation` + +Triggered when a user is invited to join an organization + +### User Organization Membership Created + +- **Method:**`POST` +- **Path:**`/webhooks/user.organization_membership_created` + +Triggered when a user joins an organization + +### User Organization Membership Deleted + +- **Method:**`POST` +- **Path:**`/webhooks/user.organization_membership_deleted` + +Triggered when a user's membership in an organization is removed or deleted + +### User Organization Membership Updated + +- **Method:**`POST` +- **Path:**`/webhooks/user.organization_membership_updated` + +Triggered when a user's organization membership is updated, e.g., change of user's role in an organization + +### Directory Enabled + +- **Method:**`POST` +- **Path:**`/webhooks/organization.directory_enabled` + +Triggered when a directory sync is enabled + +### Directory Disabled + +- **Method:**`POST` +- **Path:**`/webhooks/organization.directory_disabled` + +Triggered when a directory sync is disabled + +### Directory User Created + +- **Method:**`POST` +- **Path:**`/webhooks/organization.directory.user_created` + +Triggered when a new directory user is created + +### Directory User Updated + +- **Method:**`POST` +- **Path:**`/webhooks/organization.directory.user_updated` + +Triggered when a directory user is updated + +### Directory User Deleted + +- **Method:**`POST` +- **Path:**`/webhooks/organization.directory.user_deleted` + +Triggered when a directory user is deleted + +### Directory Group Created + +- **Method:**`POST` +- **Path:**`/webhooks/organization.directory.group_created` + +Triggered when a new directory group is created + +### Directory Group Updated + +- **Method:**`POST` +- **Path:**`/webhooks/organization.directory.group_updated` + +Triggered when a directory group is updated + +### Directory Group Deleted + +- **Method:**`POST` +- **Path:**`/webhooks/organization.directory.group_deleted` + +Triggered when a directory group is deleted + +### SSO Connection Created + +- **Method:**`POST` +- **Path:**`/webhooks/organization.sso_created` + +Triggered when a new SSO connection is created for an organization + +### SSO Connection Enabled + +- **Method:**`POST` +- **Path:**`/webhooks/organization.sso_enabled` + +Triggered when an SSO connection is enabled for an organization + +### SSO Connection Disabled + +- **Method:**`POST` +- **Path:**`/webhooks/organization.sso_disabled` + +Triggered when an SSO connection is disabled for an organization + +### SSO Connection Deleted + +- **Method:**`POST` +- **Path:**`/webhooks/organization.sso_deleted` + +Triggered when an SSO connection is deleted for an organization + +### Role Created + +- **Method:**`POST` +- **Path:**`/webhooks/role.created` + +Triggered when a new role is created + +### Role Updated + +- **Method:**`POST` +- **Path:**`/webhooks/role.updated` + +Triggered when a role is updated + +### Role Deleted + +- **Method:**`POST` +- **Path:**`/webhooks/role.deleted` + +Triggered when a role is deleted + +### Permission Created + +- **Method:**`POST` +- **Path:**`/webhooks/permission.created` + +Triggered when a new permission is created + +### Permission Updated + +- **Method:**`POST` +- **Path:**`/webhooks/permission.updated` + +Triggered when a permission is updated + +### Permission Deleted + +- **Method:**`POST` +- **Path:**`/webhooks/permission.deleted` + +Triggered when a permission is deleted + +### Connected Account Created + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.created` + +Triggered when a new connected account is created + +### Connected Account Updated + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.updated` + +Triggered when a connected account is updated + +### Connected Account Deleted + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.deleted` + +Triggered when a connected account is deleted + +### Connected Account Magic Link Generated + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.magic_link_generated` + +Triggered when a magic link is generated for OAuth flow + +### Connected Account OAuth Tokens Fetched + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.oauth_tokens_fetched` + +Triggered when OAuth tokens are successfully fetched + +### Connected Account Token Refresh Succeeded + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.token_refresh_succeeded` + +Triggered when token refresh succeeds + +### Connected Account Token Refresh Failed + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.token_refresh_failed` + +Triggered when token refresh fails + +### Connected Account OAuth Succeeded + +- **Method:**`POST` +- **Path:**`/webhooks/connected_account.oauth_succeeded` + +Triggered when OAuth authentication succeeds + +## Schemas + +### HelpInfoLink + +- **Type:**`object` + +A documentation or reference link. + +- **`description`** + + `string` — Human-readable label for the link (e.g. "User verification flow"). + +- **`url`** + + `string` — Absolute URL to the documentation page (e.g. "https\://docs.scalekit.com/..."). + +**Example:** + +```json +{ + "description": "", + "url": "" +} +``` + +### OrganizationServiceUpsertUserManagementSettingsBody + +- **Type:**`object` + +* **`settings`** + + `object` — The new values for the setting fields to patch. + + - **`max_allowed_users`** + + `integer`, format: `int32` — Maximum number of users allowed in the organization. When nil (not set), there feature is not enabled. When explicitly set to zero, it also means no limit. When set to a positive integer, it enforces the maximum user limit. + +**Example:** + +```json +{ + "settings": { + "max_allowed_users": 100 + } +} +``` + +### RolesServiceAddPermissionsToRoleBody + +- **Type:**`object` + +* **`permission_names`** + + `array` — List of permission names to add to the role + + **Items:** + + `string` + +**Example:** + +```json +{ + "permission_names": [ + "" + ] +} +``` + +### RolesServiceUpdateDefaultOrganizationRolesBody + +- **Type:**`object` + +* **`default_member_role`** + + `string` — Unique name of the default member role + +**Example:** + +```json +{ + "default_member_role": "member" +} +``` + +### UserServiceResendInviteBody + +- **Type:**`object` + +**Example:** + +```json +{} +``` + +### ValidationErrorInfoFieldViolation + +- **Type:**`object` + +A message type used to describe a single bad request field. + +- **`constraint`** + + `string` + +- **`description`** + + `string` — A description of why the request element is bad. + +- **`field`** + + `string` + +**Example:** + +```json +{ + "constraint": "", + "description": "", + "field": "" +} +``` + +### Attestation preferences for registration + +- **Type:**`object` + +* **`conveyance_preference`** + + `string` + +* **`enterprise_approved_ids`** + + `array` + + **Items:** + + `string` + +**Example:** + +```json +{ + "conveyance_preference": "", + "enterprise_approved_ids": [ + "" + ] +} +``` + +### WebAuthConfigurationAuthenticatorSelection + +- **Type:**`object` + +* **`authenticator_attachment`** + + `string` + +* **`user_verification`** + + `string` + +**Example:** + +```json +{ + "authenticator_attachment": "", + "user_verification": "" +} +``` + +### WebAuthConfigurationAuthenticators + +- **Type:**`object` + +* **`desired_authenticator_status`** + + `array` — provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate\_status set to true. + + **Items:** + + `string`, default: `"[]"` + +* **`undesired_authenticator_status`** + + `array` — provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate\_status set to true. + + **Items:** + + `string`, default: `"['ATTESTATION_KEY_COMPROMISE', 'USER_VERIFICATION_BYPASS', 'USER_KEY_REMOTE_COMPROMISE', 'USER_KEY_PHYSICAL_COMPROMISE', 'REVOKED']"` + +* **`validate_anchors`** + + `boolean` — when set to true enables the validation of the attestation statement against the trust anchor from the metadata statement. + +* **`validate_attestation_type`** + + `boolean` — when set to true enables the validation of the attestation statements type against the known types the authenticator can produce. + +* **`validate_entry`** + + `boolean` — requires that the provided metadata has an entry for the given authenticator to be considered valid. By default an AAGUID which has a zero value should fail validation if validate\_entry\_permit\_zero\_aaguid is not provided with the value of true. + +* **`validate_entry_permit_zero_aaguid`** + + `boolean` — is an option that permits a zero'd AAGUID from an attestation statement to automatically pass metadata validations. Generally helpful to use with validate\_entry. + +* **`validate_status`** + + `boolean` — when set to true enables the validation of the attestation statements AAGUID against the desired and undesired lists + +**Example:** + +```json +{ + "desired_authenticator_status": [ + "[]" + ], + "undesired_authenticator_status": [ + "['ATTESTATION_KEY_COMPROMISE', 'USER_VERIFICATION_BYPASS', 'USER_KEY_REMOTE_COMPROMISE', 'USER_KEY_PHYSICAL_COMPROMISE', 'REVOKED']" + ], + "validate_anchors": true, + "validate_attestation_type": true, + "validate_entry": true, + "validate_entry_permit_zero_aaguid": true, + "validate_status": true +} +``` + +### Rp contains relying party identifiers and origins + +- **Type:**`object` + +* **`ids`** + + `array` + + **Items:** + + `string` + +* **`origins`** + + `array` + + **Items:** + + `string` + +**Example:** + +```json +{ + "ids": [ + "" + ], + "origins": [ + "" + ] +} +``` + +### WebAuthConfigurationTimeout + +- **Type:**`object` + +* **`login`** + + `string`, default: `"\"300s\""` — Login timeout duration + +* **`login_uvd`** + + `string`, default: `"\"300s\""` — Login timeout duration when user verification is discouraged + +* **`registration`** + + `string`, default: `"\"300s\""` — Registration timeout duration + +* **`registration_uvd`** + + `string`, default: `"\"300s\""` — Registration timeout duration when user verification is discouraged + +**Example:** + +```json +{ + "login": "\"300s\"", + "login_uvd": "\"300s\"", + "registration": "\"300s\"", + "registration_uvd": "\"300s\"" +} +``` + +### WebAuthnCredentialAuthenticator + +- **Type:**`object` + +* **`aaguid`** + + `string` — Authenticator Attestation GUID (AAGUID) identifying the device model + +* **`attachment`** + + `string` — Attachment type: "platform" (built-in) or "cross-platform" + +* **`icon_dark`** + + `string` — Icon URL for dark theme display + +* **`icon_light`** + + `string` — Icon URL for light theme display + +* **`name`** + + `string` — Human-readable name of the authenticator model + +**Example:** + +```json +{ + "aaguid": "", + "attachment": "platform", + "icon_dark": "", + "icon_light": "", + "name": "Apple Touch ID" +} +``` + +### WebAuthnCredentialAuthenticatorFlags + +- **Type:**`object` + +* **`backup_eligible`** + + `boolean` — Whether this credential can be backed up to another device + +* **`backup_state`** + + `boolean` — Whether this credential was synced or backed up + +* **`user_present`** + + `boolean` — Whether the user was present during authentication + +* **`user_verified`** + + `boolean` — Whether the user was verified (e.g., fingerprint, PIN) + +**Example:** + +```json +{ + "backup_eligible": true, + "backup_state": true, + "user_present": true, + "user_verified": true +} +``` + +### WebAuthnCredentialClientInfo + +- **Type:**`object` + +* **`city`** + + `string` — City name + +* **`ip`** + + `string` — IP address from which credential was registered + +* **`region`** + + `string` — Geographic region (e.g., "US") + +* **`region_subdivision`** + + `string` — Regional subdivision (e.g., "CA") + +**Example:** + +```json +{ + "city": "San Francisco", + "ip": "192.0.2.1", + "region": "US", + "region_subdivision": "CA" +} +``` + +### WebAuthnCredentialUserAgent + +- **Type:**`object` + +* **`browser`** + + `string` — Browser name (e.g., "Chrome", "Safari") + +* **`browser_version`** + + `string` — Browser version number + +* **`device_model`** + + `string` — Device model if available + +* **`device_type`** + + `string` — Device type: "desktop", "mobile", or "tablet" + +* **`os`** + + `string` — Operating system name (e.g., "Windows", "iOS") + +* **`os_version`** + + `string` — Operating system version + +* **`raw`** + + `string` — Raw user agent string from the browser + +* **`url`** + + `string` — Parsed user agent URL reference + +**Example:** + +```json +{ + "browser": "Chrome", + "browser_version": "120.0.6099.129", + "device_model": "iPhone15,2", + "device_type": "mobile", + "os": "macOS", + "os_version": "14.2", + "raw": "", + "url": "" +} +``` + +### WebAuthnServiceUpdateCredentialBody + +- **Type:**`object` + +* **`display_name`** + + `string` — Human-friendly name for this credential (1-120 characters) + +**Example:** + +```json +{ + "display_name": "My iPhone 15 Pro" +} +``` + +### authpasswordlessPasswordlessType + +- **Type:**`string` + +**Example:** + +### Client Secret + +- **Type:**`object` + +A secure credential used for authenticating an API client. Each client can have multiple secrets for key rotation purposes. + +- **`create_time`** + + `string`, format: `date-time` — The timestamp when this secret was created. This field is automatically set by the server and cannot be modified. + +- **`created_by`** + + `string` — The identifier of the user or system that created this secret. This field helps track who created the secret for audit and compliance purposes. + +- **`expire_time`** + + `string`, format: `date-time` — The timestamp when this secret will expire. After this time, the secret cannot be used for authentication regardless of its status. If not set, the secret does not expire. + +- **`id`** + + `string` — The unique identifier for this client secret. This ID is used to reference the secret in API requests for management operations like updating or deleting the secret. + +- **`last_used_time`** + + `string`, format: `date-time` — The timestamp when this secret was last used for authentication. This field helps track secret usage for security monitoring and identifying unused secrets that may be candidates for rotation. + +- **`plain_secret`** + + `string` — The full plaintext secret value. This field is only populated when the secret is first created and is never stored by the server. It must be securely stored by the client application as it cannot be retrieved again. + +- **`secret_suffix`** + + `string` — A suffix that helps identify this secret. This is the last few characters of the full secret value but is not sufficient for authentication. Helps identify which secret is being used in logs and debugging. + +- **`status`** + + `string`, possible values: `"INACTIVE"` — The current status of this secret. A secret must be ACTIVE to be used for authentication. INACTIVE secrets cannot be used for authentication but are retained for audit purposes. + +- **`update_time`** + + `string`, format: `date-time` — The timestamp when this secret was last updated. This field is automatically updated by the server when the secret's status changes or other properties are modified. + +**Example:** + +```json +{ + "create_time": "2024-01-05T14:48:00Z", + "created_by": "user_12345", + "expire_time": "2025-01-05T14:48:00Z", + "id": "sec_1234abcd5678efgh", + "last_used_time": "2024-02-15T10:30:00Z", + "plain_secret": "sec_1234567890abcdefghijklmnopqrstuvwxyz", + "secret_suffix": "xyzw", + "status": "INACTIVE", + "update_time": "2024-01-10T09:12:00Z" +} +``` + +### clientsClientSecretStatus + +- **Type:**`string` + +ClientSecretStatus indicates whether a client secret can be used for authentication. ACTIVE secrets can be used for authentication while INACTIVE secrets cannot. + +- INACTIVE: The secret is inactive and cannot be used for authentication + +**Example:** + +### clientsCreateOrganizationClientResponse + +- **Type:**`object` + +* **`client`** + + `object` — Details of the created client + + - **`audience`** + + `array` — The intended recipients of access tokens issued to this client. Each audience value should be a URI that identifies an API or service. + + **Items:** + + `string` + + - **`client_id`** + + `string` — The unique identifier for this API client. This ID is used to identify the client in API requests and logs. It is automatically generated when the client is created and cannot be modified. + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this API client was created. This field is automatically set by the server and cannot be modified. + + - **`custom_claims`** + + `array` — Additional claims included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. + + **Items:** + + - **`key`** + + `string` — The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose. + + - **`value`** + + `string` — The value of the custom claim. This value will be included in access tokens issued to the client. + + - **`description`** + + `string` — A detailed description of the client's purpose and usage. This helps administrators understand what the client is used for. + + - **`expiry`** + + `string`, format: `int64` — Expiry time in seconds for the token generated by the client + + - **`is_cimd`** + + `boolean` — Indicates if the client was created via Client ID Metadata Document (CIMD). CIMD clients can update their own configuration according to the CIMD specification. + + - **`is_dcr`** + + `boolean` — Indicates if the client was created via Dynamic Client Registration (DCR). Clients created through DCR may have different management and lifecycle policies compared to those created manually. + + - **`metadata_uri`** + + `string` — The URI to the client's metadata, which is utilized to obtain the client's configuration details + + - **`name`** + + `string` — The display name of the API client. This name helps identify the client in the dashboard and logs. + + - **`organization_id`** + + `string` — The ID of the organization that owns this API client. This ID is used to associate the client with the correct organization and enforce organization-specific access controls. + + - **`redirect_uris`** + + `array` — The redirect URI for this API client. This URI is used in the OAuth 2.0 authorization flow to redirect users after authentication. + + **Items:** + + `string` + + - **`resource_id`** + + `string` — The ID of the resource associated with this M2M client. This field is used to link the client to a specific resource in the system. + + - **`scopes`** + + `array` — The OAuth 2.0 scopes granted to this client. These scopes determine what resources and actions the client can access. + + **Items:** + + `string` + + - **`secrets`** + + `array` — List of client secrets associated with this client. Each secret can be used for authentication, but only the most recently created secret is typically active. Secrets are stored securely and their values are never returned after creation. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this secret was created. This field is automatically set by the server and cannot be modified. + + - **`created_by`** + + `string` — The identifier of the user or system that created this secret. This field helps track who created the secret for audit and compliance purposes. + + - **`expire_time`** + + `string`, format: `date-time` — The timestamp when this secret will expire. After this time, the secret cannot be used for authentication regardless of its status. If not set, the secret does not expire. + + - **`id`** + + `string` — The unique identifier for this client secret. This ID is used to reference the secret in API requests for management operations like updating or deleting the secret. + + - **`last_used_time`** + + `string`, format: `date-time` — The timestamp when this secret was last used for authentication. This field helps track secret usage for security monitoring and identifying unused secrets that may be candidates for rotation. + + - **`plain_secret`** + + `string` — The full plaintext secret value. This field is only populated when the secret is first created and is never stored by the server. It must be securely stored by the client application as it cannot be retrieved again. + + - **`secret_suffix`** + + `string` — A suffix that helps identify this secret. This is the last few characters of the full secret value but is not sufficient for authentication. Helps identify which secret is being used in logs and debugging. + + - **`status`** + + `string`, possible values: `"INACTIVE"` — The current status of this secret. A secret must be ACTIVE to be used for authentication. INACTIVE secrets cannot be used for authentication but are retained for audit purposes. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this secret was last updated. This field is automatically updated by the server when the secret's status changes or other properties are modified. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this API client was last updated. This field is automatically updated by the server whenever the client's configuration changes. + +* **`plain_secret`** + + `string` — Client secret value (only returned once at creation) + +**Example:** + +```json +{ + "client": { + "audience": [ + "https://api.example.com" + ], + "client_id": "m2morg_1231234233424344", + "create_time": "2024-01-05T14:48:00Z", + "custom_claims": [ + {} + ], + "description": "Service account for automated deployment processes", + "expiry": 3600, + "is_cimd": false, + "is_dcr": false, + "metadata_uri": "https://example.com/client-metadata.json", + "name": "GitHub Actions Deployment Service", + "organization_id": "org_1231234233424344", + "redirect_uris": [ + "https://example.com/callback" + ], + "resource_id": "app_1231234233424344", + "scopes": [ + "deploy:resources", + "read:deployments" + ], + "secrets": [ + {} + ], + "update_time": "2024-01-05T14:48:00Z" + }, + "plain_secret": "CdExsdErfccxDDssddfffgfeFHH1" +} +``` + +### clientsCreateOrganizationClientSecretResponse + +- **Type:**`object` + +* **`plain_secret`** + + `string` — Client secret value (only returned once at creation) + +* **`secret`** + + `object` — Details of the created client secret + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this secret was created. This field is automatically set by the server and cannot be modified. + + - **`created_by`** + + `string` — The identifier of the user or system that created this secret. This field helps track who created the secret for audit and compliance purposes. + + - **`expire_time`** + + `string`, format: `date-time` — The timestamp when this secret will expire. After this time, the secret cannot be used for authentication regardless of its status. If not set, the secret does not expire. + + - **`id`** + + `string` — The unique identifier for this client secret. This ID is used to reference the secret in API requests for management operations like updating or deleting the secret. + + - **`last_used_time`** + + `string`, format: `date-time` — The timestamp when this secret was last used for authentication. This field helps track secret usage for security monitoring and identifying unused secrets that may be candidates for rotation. + + - **`plain_secret`** + + `string` — The full plaintext secret value. This field is only populated when the secret is first created and is never stored by the server. It must be securely stored by the client application as it cannot be retrieved again. + + - **`secret_suffix`** + + `string` — A suffix that helps identify this secret. This is the last few characters of the full secret value but is not sufficient for authentication. Helps identify which secret is being used in logs and debugging. + + - **`status`** + + `string`, possible values: `"INACTIVE"` — The current status of this secret. A secret must be ACTIVE to be used for authentication. INACTIVE secrets cannot be used for authentication but are retained for audit purposes. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this secret was last updated. This field is automatically updated by the server when the secret's status changes or other properties are modified. + +**Example:** + +```json +{ + "plain_secret": "m2morg_client_secret_xyz123", + "secret": { + "create_time": "2024-01-05T14:48:00Z", + "created_by": "user_12345", + "expire_time": "2025-01-05T14:48:00Z", + "id": "sec_1234abcd5678efgh", + "last_used_time": "2024-02-15T10:30:00Z", + "plain_secret": "sec_1234567890abcdefghijklmnopqrstuvwxyz", + "secret_suffix": "xyzw", + "status": "INACTIVE", + "update_time": "2024-01-10T09:12:00Z" + } +} +``` + +### clientsCustomClaim + +- **Type:**`object` + +* **`key`** + + `string` — The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose. + +* **`value`** + + `string` — The value of the custom claim. This value will be included in access tokens issued to the client. + +**Example:** + +```json +{ + "key": "environment", + "value": "production" +} +``` + +### clientsGetOrganizationClientResponse + +- **Type:**`object` + +* **`client`** + + `object` — Details of the requested client + + - **`audience`** + + `array` — The intended recipients of access tokens issued to this client. Each audience value should be a URI that identifies an API or service. + + **Items:** + + `string` + + - **`client_id`** + + `string` — The unique identifier for this API client. This ID is used to identify the client in API requests and logs. It is automatically generated when the client is created and cannot be modified. + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this API client was created. This field is automatically set by the server and cannot be modified. + + - **`custom_claims`** + + `array` — Additional claims included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. + + **Items:** + + - **`key`** + + `string` — The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose. + + - **`value`** + + `string` — The value of the custom claim. This value will be included in access tokens issued to the client. + + - **`description`** + + `string` — A detailed description of the client's purpose and usage. This helps administrators understand what the client is used for. + + - **`expiry`** + + `string`, format: `int64` — Expiry time in seconds for the token generated by the client + + - **`is_cimd`** + + `boolean` — Indicates if the client was created via Client ID Metadata Document (CIMD). CIMD clients can update their own configuration according to the CIMD specification. + + - **`is_dcr`** + + `boolean` — Indicates if the client was created via Dynamic Client Registration (DCR). Clients created through DCR may have different management and lifecycle policies compared to those created manually. + + - **`metadata_uri`** + + `string` — The URI to the client's metadata, which is utilized to obtain the client's configuration details + + - **`name`** + + `string` — The display name of the API client. This name helps identify the client in the dashboard and logs. + + - **`organization_id`** + + `string` — The ID of the organization that owns this API client. This ID is used to associate the client with the correct organization and enforce organization-specific access controls. + + - **`redirect_uris`** + + `array` — The redirect URI for this API client. This URI is used in the OAuth 2.0 authorization flow to redirect users after authentication. + + **Items:** + + `string` + + - **`resource_id`** + + `string` — The ID of the resource associated with this M2M client. This field is used to link the client to a specific resource in the system. + + - **`scopes`** + + `array` — The OAuth 2.0 scopes granted to this client. These scopes determine what resources and actions the client can access. + + **Items:** + + `string` + + - **`secrets`** + + `array` — List of client secrets associated with this client. Each secret can be used for authentication, but only the most recently created secret is typically active. Secrets are stored securely and their values are never returned after creation. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this secret was created. This field is automatically set by the server and cannot be modified. + + - **`created_by`** + + `string` — The identifier of the user or system that created this secret. This field helps track who created the secret for audit and compliance purposes. + + - **`expire_time`** + + `string`, format: `date-time` — The timestamp when this secret will expire. After this time, the secret cannot be used for authentication regardless of its status. If not set, the secret does not expire. + + - **`id`** + + `string` — The unique identifier for this client secret. This ID is used to reference the secret in API requests for management operations like updating or deleting the secret. + + - **`last_used_time`** + + `string`, format: `date-time` — The timestamp when this secret was last used for authentication. This field helps track secret usage for security monitoring and identifying unused secrets that may be candidates for rotation. + + - **`plain_secret`** + + `string` — The full plaintext secret value. This field is only populated when the secret is first created and is never stored by the server. It must be securely stored by the client application as it cannot be retrieved again. + + - **`secret_suffix`** + + `string` — A suffix that helps identify this secret. This is the last few characters of the full secret value but is not sufficient for authentication. Helps identify which secret is being used in logs and debugging. + + - **`status`** + + `string`, possible values: `"INACTIVE"` — The current status of this secret. A secret must be ACTIVE to be used for authentication. INACTIVE secrets cannot be used for authentication but are retained for audit purposes. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this secret was last updated. This field is automatically updated by the server when the secret's status changes or other properties are modified. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this API client was last updated. This field is automatically updated by the server whenever the client's configuration changes. + +**Example:** + +```json +{ + "client": { + "audience": [ + "https://api.example.com" + ], + "client_id": "m2morg_1231234233424344", + "create_time": "2024-01-05T14:48:00Z", + "custom_claims": [ + {} + ], + "description": "Service account for automated deployment processes", + "expiry": 3600, + "is_cimd": false, + "is_dcr": false, + "metadata_uri": "https://example.com/client-metadata.json", + "name": "GitHub Actions Deployment Service", + "organization_id": "org_1231234233424344", + "redirect_uris": [ + "https://example.com/callback" + ], + "resource_id": "app_1231234233424344", + "scopes": [ + "deploy:resources", + "read:deployments" + ], + "secrets": [ + {} + ], + "update_time": "2024-01-05T14:48:00Z" + } +} +``` + +### List Organization Clients Response + +- **Type:**`object` + +Response message containing a paginated list of API clients for the specified organization. + +- **`clients`** + + `array` — List of API client objects for the organization. Each client includes its configuration, metadata, and active secrets (without exposing actual secret values). + + **Items:** + + - **`audience`** + + `array` — The intended recipients of access tokens issued to this client. Each audience value should be a URI that identifies an API or service. + + **Items:** + + `string` + + - **`client_id`** + + `string` — The unique identifier for this API client. This ID is used to identify the client in API requests and logs. It is automatically generated when the client is created and cannot be modified. + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this API client was created. This field is automatically set by the server and cannot be modified. + + - **`custom_claims`** + + `array` — Additional claims included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. + + **Items:** + + - **`key`** + + `string` — The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose. + + - **`value`** + + `string` — The value of the custom claim. This value will be included in access tokens issued to the client. + + - **`description`** + + `string` — A detailed description of the client's purpose and usage. This helps administrators understand what the client is used for. + + - **`expiry`** + + `string`, format: `int64` — Expiry time in seconds for the token generated by the client + + - **`is_cimd`** + + `boolean` — Indicates if the client was created via Client ID Metadata Document (CIMD). CIMD clients can update their own configuration according to the CIMD specification. + + - **`is_dcr`** + + `boolean` — Indicates if the client was created via Dynamic Client Registration (DCR). Clients created through DCR may have different management and lifecycle policies compared to those created manually. + + - **`metadata_uri`** + + `string` — The URI to the client's metadata, which is utilized to obtain the client's configuration details + + - **`name`** + + `string` — The display name of the API client. This name helps identify the client in the dashboard and logs. + + - **`organization_id`** + + `string` — The ID of the organization that owns this API client. This ID is used to associate the client with the correct organization and enforce organization-specific access controls. + + - **`redirect_uris`** + + `array` — The redirect URI for this API client. This URI is used in the OAuth 2.0 authorization flow to redirect users after authentication. + + **Items:** + + `string` + + - **`resource_id`** + + `string` — The ID of the resource associated with this M2M client. This field is used to link the client to a specific resource in the system. + + - **`scopes`** + + `array` — The OAuth 2.0 scopes granted to this client. These scopes determine what resources and actions the client can access. + + **Items:** + + `string` + + - **`secrets`** + + `array` — List of client secrets associated with this client. Each secret can be used for authentication, but only the most recently created secret is typically active. Secrets are stored securely and their values are never returned after creation. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this secret was created. This field is automatically set by the server and cannot be modified. + + - **`created_by`** + + `string` — The identifier of the user or system that created this secret. This field helps track who created the secret for audit and compliance purposes. + + - **`expire_time`** + + `string`, format: `date-time` — The timestamp when this secret will expire. After this time, the secret cannot be used for authentication regardless of its status. If not set, the secret does not expire. + + - **`id`** + + `string` — The unique identifier for this client secret. This ID is used to reference the secret in API requests for management operations like updating or deleting the secret. + + - **`last_used_time`** + + `string`, format: `date-time` — The timestamp when this secret was last used for authentication. This field helps track secret usage for security monitoring and identifying unused secrets that may be candidates for rotation. + + - **`plain_secret`** + + `string` — The full plaintext secret value. This field is only populated when the secret is first created and is never stored by the server. It must be securely stored by the client application as it cannot be retrieved again. + + - **`secret_suffix`** + + `string` — A suffix that helps identify this secret. This is the last few characters of the full secret value but is not sufficient for authentication. Helps identify which secret is being used in logs and debugging. + + - **`status`** + + `string`, possible values: `"INACTIVE"` — The current status of this secret. A secret must be ACTIVE to be used for authentication. INACTIVE secrets cannot be used for authentication but are retained for audit purposes. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this secret was last updated. This field is automatically updated by the server when the secret's status changes or other properties are modified. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this API client was last updated. This field is automatically updated by the server whenever the client's configuration changes. + +- **`next_page_token`** + + `string` — Pagination token for the next page of results. Use this token to fetch the next page. + +- **`prev_page_token`** + + `string` — Pagination token for the previous page of results. Use this token to fetch the previous page. + +- **`total_size`** + + `integer`, format: `int64` — Total number of API clients in the organization. + +**Example:** + +```json +{ + "clients": [ + { + "audience": [ + "https://api.example.com" + ], + "client_id": "m2morg_1231234233424344", + "create_time": "2024-01-05T14:48:00Z", + "custom_claims": [ + {} + ], + "description": "Service account for automated deployment processes", + "expiry": 3600, + "is_cimd": false, + "is_dcr": false, + "metadata_uri": "https://example.com/client-metadata.json", + "name": "GitHub Actions Deployment Service", + "organization_id": "org_1231234233424344", + "redirect_uris": [ + "https://example.com/callback" + ], + "resource_id": "app_1231234233424344", + "scopes": [ + "deploy:resources", + "read:deployments" + ], + "secrets": [ + {} + ], + "update_time": "2024-01-05T14:48:00Z" + } + ], + "next_page_token": "", + "prev_page_token": "", + "total_size": 30 +} +``` + +### clientsM2MClient + +- **Type:**`object` + +* **`audience`** + + `array` — The intended recipients of access tokens issued to this client. Each audience value should be a URI that identifies an API or service. + + **Items:** + + `string` + +* **`client_id`** + + `string` — The unique identifier for this API client. This ID is used to identify the client in API requests and logs. It is automatically generated when the client is created and cannot be modified. + +* **`create_time`** + + `string`, format: `date-time` — The timestamp when this API client was created. This field is automatically set by the server and cannot be modified. + +* **`custom_claims`** + + `array` — Additional claims included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. + + **Items:** + + - **`key`** + + `string` — The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose. + + - **`value`** + + `string` — The value of the custom claim. This value will be included in access tokens issued to the client. + +* **`description`** + + `string` — A detailed description of the client's purpose and usage. This helps administrators understand what the client is used for. + +* **`expiry`** + + `string`, format: `int64` — Expiry time in seconds for the token generated by the client + +* **`is_cimd`** + + `boolean` — Indicates if the client was created via Client ID Metadata Document (CIMD). CIMD clients can update their own configuration according to the CIMD specification. + +* **`is_dcr`** + + `boolean` — Indicates if the client was created via Dynamic Client Registration (DCR). Clients created through DCR may have different management and lifecycle policies compared to those created manually. + +* **`metadata_uri`** + + `string` — The URI to the client's metadata, which is utilized to obtain the client's configuration details + +* **`name`** + + `string` — The display name of the API client. This name helps identify the client in the dashboard and logs. + +* **`organization_id`** + + `string` — The ID of the organization that owns this API client. This ID is used to associate the client with the correct organization and enforce organization-specific access controls. + +* **`redirect_uris`** + + `array` — The redirect URI for this API client. This URI is used in the OAuth 2.0 authorization flow to redirect users after authentication. + + **Items:** + + `string` + +* **`resource_id`** + + `string` — The ID of the resource associated with this M2M client. This field is used to link the client to a specific resource in the system. + +* **`scopes`** + + `array` — The OAuth 2.0 scopes granted to this client. These scopes determine what resources and actions the client can access. + + **Items:** + + `string` + +* **`secrets`** + + `array` — List of client secrets associated with this client. Each secret can be used for authentication, but only the most recently created secret is typically active. Secrets are stored securely and their values are never returned after creation. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this secret was created. This field is automatically set by the server and cannot be modified. + + - **`created_by`** + + `string` — The identifier of the user or system that created this secret. This field helps track who created the secret for audit and compliance purposes. + + - **`expire_time`** + + `string`, format: `date-time` — The timestamp when this secret will expire. After this time, the secret cannot be used for authentication regardless of its status. If not set, the secret does not expire. + + - **`id`** + + `string` — The unique identifier for this client secret. This ID is used to reference the secret in API requests for management operations like updating or deleting the secret. + + - **`last_used_time`** + + `string`, format: `date-time` — The timestamp when this secret was last used for authentication. This field helps track secret usage for security monitoring and identifying unused secrets that may be candidates for rotation. + + - **`plain_secret`** + + `string` — The full plaintext secret value. This field is only populated when the secret is first created and is never stored by the server. It must be securely stored by the client application as it cannot be retrieved again. + + - **`secret_suffix`** + + `string` — A suffix that helps identify this secret. This is the last few characters of the full secret value but is not sufficient for authentication. Helps identify which secret is being used in logs and debugging. + + - **`status`** + + `string`, possible values: `"INACTIVE"` — The current status of this secret. A secret must be ACTIVE to be used for authentication. INACTIVE secrets cannot be used for authentication but are retained for audit purposes. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this secret was last updated. This field is automatically updated by the server when the secret's status changes or other properties are modified. + +* **`update_time`** + + `string`, format: `date-time` — The timestamp when this API client was last updated. This field is automatically updated by the server whenever the client's configuration changes. + +**Example:** + +```json +{ + "audience": [ + "https://api.example.com" + ], + "client_id": "m2morg_1231234233424344", + "create_time": "2024-01-05T14:48:00Z", + "custom_claims": [ + { + "key": "environment", + "value": "production" + } + ], + "description": "Service account for automated deployment processes", + "expiry": 3600, + "is_cimd": false, + "is_dcr": false, + "metadata_uri": "https://example.com/client-metadata.json", + "name": "GitHub Actions Deployment Service", + "organization_id": "org_1231234233424344", + "redirect_uris": [ + "https://example.com/callback" + ], + "resource_id": "app_1231234233424344", + "scopes": [ + "deploy:resources", + "read:deployments" + ], + "secrets": [ + { + "create_time": "2024-01-05T14:48:00Z", + "created_by": "user_12345", + "expire_time": "2025-01-05T14:48:00Z", + "id": "sec_1234abcd5678efgh", + "last_used_time": "2024-02-15T10:30:00Z", + "plain_secret": "sec_1234567890abcdefghijklmnopqrstuvwxyz", + "secret_suffix": "xyzw", + "status": "INACTIVE", + "update_time": "2024-01-10T09:12:00Z" + } + ], + "update_time": "2024-01-05T14:48:00Z" +} +``` + +### clientsOrganizationClient + +- **Type:**`object` + +* **`audience`** + + `array` — The intended recipients of the access tokens issued to this client. Each audience value should be a URI that identifies the API or service that will validate the token. + + **Items:** + + `string` + +* **`custom_claims`** + + `array` — Additional claims to be included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. Keep claims minimal to avoid increasing token size. + + **Items:** + + - **`key`** + + `string` — The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose. + + - **`value`** + + `string` — The value of the custom claim. This value will be included in access tokens issued to the client. + +* **`description`** + + `string` — A detailed explanation of the client's purpose and usage. This helps administrators understand what the client is used for and who manages it. + +* **`expiry`** + + `string`, format: `int64` — Expiry time in seconds for the token generated by the client + +* **`name`** + + `string` — A descriptive name for the API client that helps identify its purpose. This name is displayed in the dashboard and logs. Must be between 1 and 128 characters. + +* **`scopes`** + + `array` — OAuth 2.0 scopes that define the permissions granted to this client. Each scope represents a specific permission or set of permissions. The client can only access resources that match its granted scopes. + + **Items:** + + `string` + +**Example:** + +```json +{ + "audience": [ + "https://api.example.com/api/analytics", + "https://deployment-api.acmecorp.com" + ], + "custom_claims": [ + { + "key": "environment", + "value": "production" + }, + { + "key": "service", + "value": "deployment" + } + ], + "description": "Service account for GitHub Actions to deploy resources to production", + "expiry": 3600, + "name": "GitHub Actions Deployment Service", + "scopes": [ + "deploy:resources", + "read:deployments" + ] +} +``` + +### clientsUpdateOrganizationClientResponse + +- **Type:**`object` + +* **`client`** + + `object` — Updated details of the client + + - **`audience`** + + `array` — The intended recipients of access tokens issued to this client. Each audience value should be a URI that identifies an API or service. + + **Items:** + + `string` + + - **`client_id`** + + `string` — The unique identifier for this API client. This ID is used to identify the client in API requests and logs. It is automatically generated when the client is created and cannot be modified. + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this API client was created. This field is automatically set by the server and cannot be modified. + + - **`custom_claims`** + + `array` — Additional claims included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. + + **Items:** + + - **`key`** + + `string` — The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose. + + - **`value`** + + `string` — The value of the custom claim. This value will be included in access tokens issued to the client. + + - **`description`** + + `string` — A detailed description of the client's purpose and usage. This helps administrators understand what the client is used for. + + - **`expiry`** + + `string`, format: `int64` — Expiry time in seconds for the token generated by the client + + - **`is_cimd`** + + `boolean` — Indicates if the client was created via Client ID Metadata Document (CIMD). CIMD clients can update their own configuration according to the CIMD specification. + + - **`is_dcr`** + + `boolean` — Indicates if the client was created via Dynamic Client Registration (DCR). Clients created through DCR may have different management and lifecycle policies compared to those created manually. + + - **`metadata_uri`** + + `string` — The URI to the client's metadata, which is utilized to obtain the client's configuration details + + - **`name`** + + `string` — The display name of the API client. This name helps identify the client in the dashboard and logs. + + - **`organization_id`** + + `string` — The ID of the organization that owns this API client. This ID is used to associate the client with the correct organization and enforce organization-specific access controls. + + - **`redirect_uris`** + + `array` — The redirect URI for this API client. This URI is used in the OAuth 2.0 authorization flow to redirect users after authentication. + + **Items:** + + `string` + + - **`resource_id`** + + `string` — The ID of the resource associated with this M2M client. This field is used to link the client to a specific resource in the system. + + - **`scopes`** + + `array` — The OAuth 2.0 scopes granted to this client. These scopes determine what resources and actions the client can access. + + **Items:** + + `string` + + - **`secrets`** + + `array` — List of client secrets associated with this client. Each secret can be used for authentication, but only the most recently created secret is typically active. Secrets are stored securely and their values are never returned after creation. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — The timestamp when this secret was created. This field is automatically set by the server and cannot be modified. + + - **`created_by`** + + `string` — The identifier of the user or system that created this secret. This field helps track who created the secret for audit and compliance purposes. + + - **`expire_time`** + + `string`, format: `date-time` — The timestamp when this secret will expire. After this time, the secret cannot be used for authentication regardless of its status. If not set, the secret does not expire. + + - **`id`** + + `string` — The unique identifier for this client secret. This ID is used to reference the secret in API requests for management operations like updating or deleting the secret. + + - **`last_used_time`** + + `string`, format: `date-time` — The timestamp when this secret was last used for authentication. This field helps track secret usage for security monitoring and identifying unused secrets that may be candidates for rotation. + + - **`plain_secret`** + + `string` — The full plaintext secret value. This field is only populated when the secret is first created and is never stored by the server. It must be securely stored by the client application as it cannot be retrieved again. + + - **`secret_suffix`** + + `string` — A suffix that helps identify this secret. This is the last few characters of the full secret value but is not sufficient for authentication. Helps identify which secret is being used in logs and debugging. + + - **`status`** + + `string`, possible values: `"INACTIVE"` — The current status of this secret. A secret must be ACTIVE to be used for authentication. INACTIVE secrets cannot be used for authentication but are retained for audit purposes. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this secret was last updated. This field is automatically updated by the server when the secret's status changes or other properties are modified. + + - **`update_time`** + + `string`, format: `date-time` — The timestamp when this API client was last updated. This field is automatically updated by the server whenever the client's configuration changes. + +**Example:** + +```json +{ + "client": { + "audience": [ + "https://api.example.com" + ], + "client_id": "m2morg_1231234233424344", + "create_time": "2024-01-05T14:48:00Z", + "custom_claims": [ + {} + ], + "description": "Service account for automated deployment processes", + "expiry": 3600, + "is_cimd": false, + "is_dcr": false, + "metadata_uri": "https://example.com/client-metadata.json", + "name": "GitHub Actions Deployment Service", + "organization_id": "org_1231234233424344", + "redirect_uris": [ + "https://example.com/callback" + ], + "resource_id": "app_1231234233424344", + "scopes": [ + "deploy:resources", + "read:deployments" + ], + "secrets": [ + {} + ], + "update_time": "2024-01-05T14:48:00Z" + } +} +``` + +### commonsExternalIdentity + +- **Type:**`object` + +* **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + +* **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + +* **`connection_type`** + + `string` — Name of the external identity connection. + +* **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + +* **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + +* **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + +* **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + +* **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + +**Example:** + +```json +{ + "connection_id": "conn_1234abcd5678efgh", + "connection_provider": "GOOGLE", + "connection_type": "OAUTH", + "connection_user_id": "ext_user_12345", + "created_time": "", + "is_social": true, + "last_login_time": "", + "last_synced_time": "" +} +``` + +### commonsIdentityProviderType + +- **Type:**`string` + +**Example:** + +### commonsMembershipStatus + +- **Type:**`string` + +**Example:** + +### commonsOrganizationMembership + +- **Type:**`object` + +* **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + +* **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + +* **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + +* **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + +* **`inviter_email`** + + `string` — ID of the user who invited this user. + +* **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + +* **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + +* **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + +* **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + +* **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + +* **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + +* **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + +* **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + +**Example:** + +```json +{ + "accepted_at": "", + "created_at": "", + "display_name": "Acme Corporation", + "expires_at": "", + "inviter_email": "", + "join_time": "", + "membership_status": "ACTIVE", + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "name": "AcmeCorp", + "organization_id": "org_1234abcd5678efgh", + "permissions": [ + "read_projects", + "write_tasks", + "manage_users" + ], + "provisioning_method": "", + "roles": [ + { + "display_name": "Dev Team", + "id": "role_79643236410327240", + "name": "team_dev" + } + ] +} +``` + +### commonsRegionCode + +- **Type:**`string` + +**Example:** + +### commonsRole + +- **Type:**`object` + +* **`display_name`** + + `string` — Human-readable name for the role + +* **`id`** + + `string` — Role ID + +* **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + +**Example:** + +```json +{ + "display_name": "Dev Team", + "id": "role_79643236410327240", + "name": "team_dev" +} +``` + +### commonsUserProfile + +- **Type:**`object` + +* **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + +* **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + +* **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + +* **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + +* **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + +* **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + +* **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + +* **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + +* **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + +* **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + +* **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + +* **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + +* **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + +* **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + +* **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "custom_attributes": { + "department": "engineering", + "security_clearance": "level2" + }, + "email_verified": true, + "external_identities": [ + { + "connection_id": "conn_1234abcd5678efgh", + "connection_provider": "GOOGLE", + "connection_type": "OAUTH", + "connection_user_id": "ext_user_12345", + "created_time": "", + "is_social": true, + "last_login_time": "", + "last_synced_time": "" + } + ], + "family_name": "Doe", + "gender": "male", + "given_name": "John", + "groups": [ + "admin", + "developer" + ], + "id": "usr_profile_1234abcd5678efgh", + "locale": "en-US", + "metadata": { + "department": "engineering", + "employee_type": "full-time", + "idp_user_id": "12345" + }, + "name": "John Michael Doe", + "phone_number": "+14155552671", + "phone_number_verified": true, + "picture": "https://example.com/avatar.jpg", + "preferred_username": "johndoe" +} +``` + +### Authentication credentials container supporting multiple auth types + +- **Type:**`object` + +* **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + +* **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +**Example:** + +```json +{ + "oauth_token": { + "access_token": "ya29.a0AfH6SMBx...", + "domain": "example.com", + "refresh_token": "1//0gHJxZ-Lb2...", + "scopes": [ + "https://www.googleapis.com/auth/drive.readonly", + "https://www.googleapis.com/auth/userinfo.email" + ] + }, + "static_auth": { + "details": { + "api_key": "sk_live_...", + "api_secret": "..." + } + } +} +``` + +### connected\_accountsConnectedAccount + +- **Type:**`object` + +* **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. + +* **`authorization_details`** + + `object` — Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +* **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. + +* **`connection_id`** + + `string` — Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. + +* **`connector`** + + `string` — Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to. + +* **`id`** + + `string` — Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca\_'. + +* **`identifier`** + + `string` — The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier. + +* **`last_used_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. + +* **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection. + +* **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. + +* **`token_expires_at`** + + `string`, format: `date-time` — Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. + +* **`updated_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. + +**Example:** + +```json +{ + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": { + "oauth_token": null, + "static_auth": null + }, + "authorization_type": "OAUTH", + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": "ACTIVE", + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" +} +``` + +### Connected account summary for list operations - excludes sensitive authorization details + +- **Type:**`object` + +* **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Authorization mechanism type. + +* **`connection_id`** + + `string` — Parent connection configuration reference. + +* **`connector`** + + `string` — Connector identifier. + +* **`id`** + + `string` — Unique connected account identifier. + +* **`identifier`** + + `string` — The unique identifier for this account in the third-party service. + +* **`last_used_at`** + + `string`, format: `date-time` — Last usage timestamp. + +* **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft'). + +* **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current connection status. + +* **`token_expires_at`** + + `string`, format: `date-time` — Token expiration timestamp. + +* **`updated_at`** + + `string`, format: `date-time` — Last modification timestamp. + +**Example:** + +```json +{ + "authorization_type": "OAUTH", + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": "ACTIVE", + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" +} +``` + +### Status of a connected account indicating its current state + +- **Type:**`string` + +* ACTIVE: Account is connected and credentials are valid +* EXPIRED: Access token has expired and needs refresh +* PENDING\_AUTH: Account awaiting user authorization (re-auth initiated) +* PENDING\_VERIFICATION: OAuth complete; awaiting user identity verification before activation + +**Example:** + +### Type of authentication mechanism used for the connected account + +- **Type:**`string` + +* OAUTH: OAuth 2.0 authorization with access and refresh tokens +* API\_KEY: Static API key authentication +* BASIC\_AUTH: HTTP Basic Authentication (username/password) +* BEARER\_TOKEN: Bearer token authentication +* CUSTOM: Custom authentication mechanism +* BASIC: Basic authentication (alias) + +**Example:** + +### connected\_accountsCreateConnectedAccountRequest + +- **Type:**`object` + +* **`connected_account`** + + `object` — Details of the connected account to create + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom API endpoints, timeouts, or feature flags. + + - **`authorization_details`** + + `object` — Optional authentication credentials for the connected account. Include OAuth tokens (access\_token, refresh\_token, scopes) or static auth details (API keys, bearer tokens). Can be provided later via update. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +* **`connector`** + + `string` — Connector identifier + +* **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +* **`organization_id`** + + `string` — Organization ID for the connector + +* **`user_id`** + + `string` — User ID for the connector + +**Example:** + +```json +{ + "connected_account": { + "authorization_details": { + "oauth_token": { + "access_token": "...", + "refresh_token": "...", + "scopes": [ + "read", + "write" + ] + } + }, + "authorization_type": "OAUTH2" + }, + "connector": "notion", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "user_id": "user_121312434123312" +} +``` + +### connected\_accountsCreateConnectedAccountResponse + +- **Type:**`object` + +* **`connected_account`** + + `object` — The newly created connected account with its unique identifier, status, and complete authorization details including access tokens. + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. + + - **`authorization_details`** + + `object` — Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. + + - **`connection_id`** + + `string` — Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. + + - **`connector`** + + `string` — Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to. + + - **`id`** + + `string` — Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca\_'. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier. + + - **`last_used_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection. + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. + + - **`token_expires_at`** + + `string`, format: `date-time` — Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. + +**Example:** + +```json +{ + "connected_account": { + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": null, + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } +} +``` + +### connected\_accountsDeleteConnectedAccountRequest + +- **Type:**`object` + +* **`connector`** + + `string` — Connector identifier + +* **`id`** + + `string` — Unique identifier for the connected account to delete + +* **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +* **`organization_id`** + + `string` — Organization ID for the connector + +* **`user_id`** + + `string` — User ID for the connector + +**Example:** + +```json +{ + "connector": "notion", + "id": "ca_123", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "user_id": "user_121312434123312" +} +``` + +### connected\_accountsDeleteConnectedAccountResponse + +- **Type:**`object` + +**Example:** + +```json +{} +``` + +### connected\_accountsGetConnectedAccountByIdentifierResponse + +- **Type:**`object` + +* **`connected_account`** + + `object` — The connected account with complete details including sensitive authorization credentials (access tokens, refresh tokens, scopes). Handle with appropriate access controls. + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. + + - **`authorization_details`** + + `object` — Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. + + - **`connection_id`** + + `string` — Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. + + - **`connector`** + + `string` — Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to. + + - **`id`** + + `string` — Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca\_'. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier. + + - **`last_used_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection. + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. + + - **`token_expires_at`** + + `string`, format: `date-time` — Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. + +**Example:** + +```json +{ + "connected_account": { + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": null, + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } +} +``` + +### connected\_accountsGetMagicLinkForConnectedAccountRequest + +- **Type:**`object` + +* **`connector`** + + `string` — Connector identifier + +* **`id`** + + `string` — Unique identifier for the connected account + +* **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +* **`organization_id`** + + `string` — Organization ID for the connector + +* **`state`** + + `string` — Optional opaque state value. State added to the user verify redirect URL query params to validate the user verification + +* **`user_id`** + + `string` — User ID for the connector + +* **`user_verify_url`** + + `string` — B2B app's user verify redirect URL + +**Example:** + +```json +{ + "connector": "notion", + "id": "ca_123", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "state": "QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY=", + "user_id": "user_121312434123312", + "user_verify_url": "https://app.yourapp.com/user/verify/callback" +} +``` + +### connected\_accountsGetMagicLinkForConnectedAccountResponse + +- **Type:**`object` + +* **`expiry`** + + `string`, format: `date-time` — Expiry timestamp for the authentication link + +* **`link`** + + `string` — Authentication link for the connector + +**Example:** + +```json +{ + "expiry": "2024-03-20T15:04:05Z", + "link": "https://notion.com/oauth/authorize?client_id=..." +} +``` + +### connected\_accountsListConnectedAccountsResponse + +- **Type:**`object` + +* **`connected_accounts`** + + `array` — List of connected accounts matching the filter criteria. Excludes sensitive authorization details for security. + + **Items:** + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Authorization mechanism type. + + - **`connection_id`** + + `string` — Parent connection configuration reference. + + - **`connector`** + + `string` — Connector identifier. + + - **`id`** + + `string` — Unique connected account identifier. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. + + - **`last_used_at`** + + `string`, format: `date-time` — Last usage timestamp. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft'). + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current connection status. + + - **`token_expires_at`** + + `string`, format: `date-time` — Token expiration timestamp. + + - **`updated_at`** + + `string`, format: `date-time` — Last modification timestamp. + +* **`next_page_token`** + + `string` — Pagination token for retrieving the next page. Empty if this is the last page. Pass this value to page\_token in the next request. + +* **`prev_page_token`** + + `string` — Pagination token for retrieving the previous page. Empty if this is the first page. Pass this value to page\_token to go back. + +* **`total_size`** + + `integer`, format: `int64` — Total count of connected accounts matching the filter criteria across all pages. Use for calculating pagination. + +**Example:** + +```json +{ + "connected_accounts": [ + { + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } + ], + "next_page_token": "eyJvZmZzZXQiOjIwfQ==", + "prev_page_token": "eyJvZmZzZXQiOjB9", + "total_size": 100 +} +``` + +### OAuth 2.0 access and refresh tokens with scopes + +- **Type:**`object` + +* **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + +* **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + +* **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + +* **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + +**Example:** + +```json +{ + "access_token": "ya29.a0AfH6SMBx...", + "domain": "example.com", + "refresh_token": "1//0gHJxZ-Lb2...", + "scopes": [ + "https://www.googleapis.com/auth/drive.readonly", + "https://www.googleapis.com/auth/userinfo.email" + ] +} +``` + +### connected\_accountsSearchConnectedAccountsResponse + +- **Type:**`object` + +* **`connected_accounts`** + + `array` — List of connected accounts matching the search query. Excludes sensitive authorization details. + + **Items:** + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Authorization mechanism type. + + - **`connection_id`** + + `string` — Parent connection configuration reference. + + - **`connector`** + + `string` — Connector identifier. + + - **`id`** + + `string` — Unique connected account identifier. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. + + - **`last_used_at`** + + `string`, format: `date-time` — Last usage timestamp. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft'). + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current connection status. + + - **`token_expires_at`** + + `string`, format: `date-time` — Token expiration timestamp. + + - **`updated_at`** + + `string`, format: `date-time` — Last modification timestamp. + +* **`next_page_token`** + + `string` — Pagination token for the next page. Empty if this is the last page. + +* **`prev_page_token`** + + `string` — Pagination token for the previous page. Empty if this is the first page. + +* **`total_size`** + + `integer`, format: `int64` — Total count of accounts matching the search query across all pages. + +**Example:** + +```json +{ + "connected_accounts": [ + { + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } + ], + "next_page_token": "eyJvZmZzZXQiOjMwfQ==", + "prev_page_token": "eyJvZmZzZXQiOjB9", + "total_size": 100 +} +``` + +### Static authentication credentials for API keys, bearer tokens, or basic auth + +- **Type:**`object` + +* **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +**Example:** + +```json +{ + "details": { + "api_key": "sk_live_...", + "api_secret": "..." + } +} +``` + +### connected\_accountsUpdateConnectedAccountRequest + +- **Type:**`object` + +* **`connected_account`** + + `object` — Details of the connected account to update + + - **`api_config`** + + `object` — Updated JSON configuration for API-specific settings. Merges with existing configuration - only provided fields are modified. + + - **`authorization_details`** + + `object` — Updated authentication credentials. Provide new OAuth tokens (e.g., after refresh) or updated static auth details. Only included fields will be modified. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +* **`connector`** + + `string` — Connector identifier + +* **`id`** + + `string` — Unique identifier for the connected account to update + +* **`identifier`** + + `string` — The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). + +* **`organization_id`** + + `string` — Organization ID for the connector + +* **`user_id`** + + `string` — User ID for the connector + +**Example:** + +```json +{ + "connected_account": { + "authorization_details": { + "oauth_token": { + "access_token": "...", + "refresh_token": "...", + "scopes": [ + "read", + "write" + ] + } + }, + "authorization_type": "OAUTH2" + }, + "connector": "notion", + "id": "ca_123", + "identifier": "user@example.com", + "organization_id": "org_121312434123312", + "user_id": "user_121312434123312" +} +``` + +### connected\_accountsUpdateConnectedAccountResponse + +- **Type:**`object` + +* **`connected_account`** + + `object` — The updated connected account with refreshed credentials, new token expiry, and modified configuration settings. + + - **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. + + - **`authorization_details`** + + `object` — Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + + - **`authorization_type`** + + `string`, possible values: `"OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"` — Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. + + - **`connection_id`** + + `string` — Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. + + - **`connector`** + + `string` — Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to. + + - **`id`** + + `string` — Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca\_'. + + - **`identifier`** + + `string` — The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier. + + - **`last_used_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. + + - **`provider`** + + `string` — OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection. + + - **`status`** + + `string`, possible values: `"ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"` — Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. + + - **`token_expires_at`** + + `string`, format: `date-time` — Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. + +**Example:** + +```json +{ + "connected_account": { + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": null, + "authorization_type": null, + "connection_id": "conn_24834495392086178", + "connector": "notion", + "id": "ca_24834495392086178", + "identifier": "user@example.com", + "last_used_at": "2024-03-20T14:30:00Z", + "provider": "google", + "status": null, + "token_expires_at": "2024-12-31T23:59:59Z", + "updated_at": "2024-03-20T15:04:05Z" + } +} +``` + +### connected\_accountsVerifyConnectedAccountUserRequest + +- **Type:**`object` + +* **`auth_request_id` (required)** + + `string` — Auth request ID as base64url-encoded opaque token from the user verify redirect URL query params + +* **`identifier` (required)** + + `string` — Current logged in user's connected account identifier + +**Example:** + +```json +{ + "auth_request_id": "QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY=", + "identifier": "user@example.com" +} +``` + +### connected\_accountsVerifyConnectedAccountUserResponse + +- **Type:**`object` + +* **`post_user_verify_redirect_url`** + + `string` — URL to redirect the user to after successful verification + +**Example:** + +```json +{ + "post_user_verify_redirect_url": "https://env1.example.com/connect/success" +} +``` + +### connectionsCodeChallengeType + +- **Type:**`string` + +**Example:** + +### connectionsConfigurationType + +- **Type:**`string` + +**Example:** + +### connectionsConnection + +- **Type:**`object` + +* **`attribute_mapping`** + + `object` — Maps identity provider attributes to user profile fields. For example, {'email': 'user.mail', 'name': 'user.displayName'}. + +* **`configuration_type`** + + `string`, possible values: `"DISCOVERY", "MANUAL"` — How the connection was configured: DISCOVERY (automatic configuration) or MANUAL (administrator configured) + +* **`debug_enabled`** + + `boolean` — Enables testing mode that allows non-HTTPS endpoints. Should only be enabled in development environments, never in production. + +* **`domains`** + + `array` — Domain associated with this connection, used for domain-based authentication flows. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the domain was first created. + + - **`domain`** + + `string` — The business domain name that was configured for allowed email domain functionality (e.g., company.com, subdomain.company.com). + + - **`domain_type`** + + `object` + + - **`environment_id`** + + `string` — The environment ID where this domain is configured. + + - **`id`** + + `string` — Scalekit-generated unique identifier for this domain record. + + - **`organization_id`** + + `string` — The organization to which the domain belongs. + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the domain was last updated. + + - **`verification_method`** + + `string`, possible values: `"ADMIN", "DNS", "NOT_APPLICABLE"` — Method that determines how domain ownership is verified. - ADMIN: domain is marked verified without DNS validation, typically by an admin. - DNS: domain must be verified by adding a TXT record to your DNS configuration. - NOT\_APPLICABLE: verification does not apply to this domain type. + + - **`verification_status`** + + `string`, possible values: `"PENDING", "VERIFIED", "FAILED", "AUTO_VERIFIED"` — Verification status of the domain. - PENDING: DNS TXT record has not been validated yet. - VERIFIED: domain confirmed via DNS TXT record validation or admin approval. - AUTO\_VERIFIED: domain verified automatically without DNS changes. - FAILED: DNS TXT record was not validated within the verification window. + +* **`enabled`** + + `boolean` — Controls whether users can sign in using this connection. When false, the connection exists but cannot be used for authentication. + +* **`id`** + + `string` — Unique identifier for this connection. Used in API calls to reference this specific connection. + +* **`key_id`** + + `string` — Alternative identifier for this connection, typically used in frontend applications or URLs. + +* **`oauth_config`** + + `object` — Configuration details for OAuth connections. Present only when type is OAUTH. + + - **`access_type`** + + `string` — Access Type + + - **`authorize_uri`** + + `string` — Authorize URI + + - **`client_id`** + + `string` — Client ID + + - **`client_secret`** + + `string` — Client Secret + + - **`custom_scope_name`** + + `string` — Custom Scope Name + + - **`pkce_enabled`** + + `boolean` — PKCE Enabled + + - **`prompt`** + + `string` — Prompt for the user + + - **`redirect_uri`** + + `string` — Redirect URI + + - **`scopes`** + + `array` — OIDC Scopes + + **Items:** + + `string` + + - **`sync_user_profile_on_login`** + + `boolean` — Indicates whether user profiles should be synchronized with the identity provider upon each log-in. + + - **`tenant_id`** + + `string` — Microsoft Entra tenant ID. Required when using a single-tenant or multi-tenant app registered in Microsoft Entra. Leave empty to use the common endpoint. + + - **`token_access_type`** + + `string` — Token Access Type + + - **`token_uri`** + + `string` — Token URI + + - **`use_platform_creds`** + + `boolean` — Use Scalekit credentials + + - **`user_info_uri`** + + `string` — User Info URI + +* **`oidc_config`** + + `object` — Configuration details for OpenID Connect (OIDC) connections. Present only when type is OIDC. + + - **`authorize_uri`** + + `string` — Authorize URI + + - **`backchannel_logout_redirect_uri`** + + `string` — backchannel logout redirect uri where idp sends logout\_token + + - **`client_id`** + + `string` — Client ID + + - **`client_secret`** + + `string` — Client Secret + + - **`discovery_endpoint`** + + `string` — Discovery Endpoint + + - **`idp_logout_required`** + + `boolean` — Enable IDP logout + + - **`issuer`** + + `string` — Issuer URL + + - **`jit_provisioning_with_sso_enabled`** + + `boolean` — Indicates if Just In Time user provisioning is enabled for the connection + + - **`jwks_uri`** + + `string` — JWKS URI + + - **`pkce_enabled`** + + `boolean` — PKCE Enabled + + - **`post_logout_redirect_uri`** + + `string` — post logout redirect uri + + - **`redirect_uri`** + + `string` — Redirect URI + + - **`scopes`** + + `array` — OIDC Scopes + + **Items:** + + `string`, possible values: `"openid", "profile", "email", "address", "phone"` + + - **`sync_user_profile_on_login`** + + `boolean` — Indicates whether user profiles should be synchronized with the identity provider upon each log-in. + + - **`token_auth_type`** + + `string`, possible values: `"URL_PARAMS", "BASIC_AUTH"` — Token Auth Type + + - **`token_uri`** + + `string` — Token URI + + - **`user_info_uri`** + + `string` — User Info URI + +* **`organization_id`** + + `string` — Identifier of the organization that owns this connection. Connections are typically scoped to a single organization. + +* **`passwordless_config`** + + `object` — Configuration details for Magic Link authentication. Present only when type is MAGIC\_LINK. + + - **`code_challenge_length`** + + `integer`, format: `int64` — Code Challenge Length + + - **`code_challenge_type`** + + `string`, possible values: `"NUMERIC", "ALPHANUMERIC"` — Code Challenge Type + + - **`enforce_same_browser_origin`** + + `boolean` — Enforce Same Browser Origin + + - **`frequency`** + + `integer`, format: `int64` — Link Frequency + + - **`regenerate_passwordless_credentials_on_resend`** + + `boolean` — Regenerate the + + - **`type`** + + `string`, possible values: `"LINK", "OTP", "LINK_OTP"` — Passwordless Type + + - **`validity`** + + `integer`, format: `int64` — Link Validity in Seconds + +* **`provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Identity provider service that handles authentication (such as OKTA, Google, Azure AD, or a custom provider) + +* **`provider_key`** + + `string` — Key ID of the identity provider service that handles authentication + +* **`saml_config`** + + `object` — Configuration details for SAML connections. Present only when type is SAML. + + - **`allow_idp_initiated_login`** + + `boolean` — Allow IDP Initiated Login + + - **`assertion_encrypted`** + + `boolean` — Assertion Encrypted + + - **`certificate_id`** + + `string` — Certificate ID + + - **`default_redirect_uri`** + + `string` — Default Redirect URI + + - **`force_authn`** + + `boolean` — Force Authn + + - **`idp_certificates`** + + `array` — IDP Certificates + + **Items:** + + - **`certificate`** + + `string` — IDP Certificate + + - **`create_time`** + + `string`, format: `date-time` — Certificate Creation Time + + - **`expiry_time`** + + `string`, format: `date-time` — Certificate Expiry Time + + - **`id`** + + `string` — Certificate ID + + - **`issuer`** + + `string` — Certificate Issuer + + - **`idp_entity_id`** + + `string` — IDP Entity ID + + - **`idp_metadata_url`** + + `string` — IDP Metadata URL + + - **`idp_name_id_format`** + + `string`, possible values: `"UNSPECIFIED", "EMAIL", "TRANSIENT", "PERSISTENT"` — IDP Name ID Format + + - **`idp_slo_request_binding`** + + `string`, possible values: `"HTTP_POST", "HTTP_REDIRECT"` — IDP SLO Request Binding + + - **`idp_slo_required`** + + `boolean` — Enable IDP logout + + - **`idp_slo_url`** + + `string` — IDP SLO URL + + - **`idp_sso_request_binding`** + + `string`, possible values: `"HTTP_POST", "HTTP_REDIRECT"` — IDP SSO Request Binding + + - **`idp_sso_url`** + + `string` — IDP SSO URL + + - **`jit_provisioning_with_sso_enabled`** + + `boolean` — Indicates if Just In Time user provisioning is enabled for the connection + + - **`saml_signing_option`** + + `string`, possible values: `"NO_SIGNING", "SAML_ONLY_RESPONSE_SIGNING", "SAML_ONLY_ASSERTION_SIGNING", "SAML_RESPONSE_ASSERTION_SIGNING", "SAML_RESPONSE_OR_ASSERTION_SIGNING"` — SAML Signing Option + + - **`sp_assertion_url`** + + `string` — SP Assertion URL + + - **`sp_entity_id`** + + `string` — SP Entity ID + + - **`sp_metadata_url`** + + `string` — SP Metadata URL + + - **`sp_slo_url`** + + `string` — Service Provider SLO url + + - **`sync_user_profile_on_login`** + + `boolean` — Indicates whether user profiles should be synchronized with the identity provider upon each log-in. + + - **`ui_button_title`** + + `string` — UI Button Title + + - **`want_request_signed`** + + `boolean` — Want Request Signed + +* **`static_config`** + + `object` — Static configuration for custom connections. Present only when type is BASIC, BEARER, API\_KEY, or custom. + + - **`static_config`** + + `object` + +* **`status`** + + `string`, possible values: `"DRAFT", "IN_PROGRESS", "COMPLETED"` — Current configuration status of the connection. Possible values include IN\_PROGRESS, CONFIGURED, and ERROR. + +* **`test_connection_uri`** + + `string` — URI that can be used to test this connection. Visit this URL to verify the connection works correctly. + +* **`type`** + + `string`, possible values: `"OIDC", "SAML", "PASSWORD", "OAUTH", "PASSWORDLESS", "BASIC", "BEARER", "API_KEY", "WEBAUTHN"` — Authentication protocol used by this connection. Can be OIDC (OpenID Connect), SAML, OAUTH, or MAGIC\_LINK. + +* **`webauthn_config`** + + `object` — Configuration details for WebAuthn (passkeys). Present only when type is WEBAUTHN. + + - **`attestation`** + + `object` + + - **`conveyance_preference`** + + `string` + + - **`enterprise_approved_ids`** + + `array` + + **Items:** + + `string` + + - **`authenticator_selection`** + + `object` + + - **`authenticator_attachment`** + + `string` + + - **`user_verification`** + + `string` + + - **`authenticators`** + + `object` + + - **`desired_authenticator_status`** + + `array` — provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate\_status set to true. + + **Items:** + + `string`, default: `"[]"` + + - **`undesired_authenticator_status`** + + `array` — provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate\_status set to true. + + **Items:** + + `string`, default: `"['ATTESTATION_KEY_COMPROMISE', 'USER_VERIFICATION_BYPASS', 'USER_KEY_REMOTE_COMPROMISE', 'USER_KEY_PHYSICAL_COMPROMISE', 'REVOKED']"` + + - **`validate_anchors`** + + `boolean` — when set to true enables the validation of the attestation statement against the trust anchor from the metadata statement. + + - **`validate_attestation_type`** + + `boolean` — when set to true enables the validation of the attestation statements type against the known types the authenticator can produce. + + - **`validate_entry`** + + `boolean` — requires that the provided metadata has an entry for the given authenticator to be considered valid. By default an AAGUID which has a zero value should fail validation if validate\_entry\_permit\_zero\_aaguid is not provided with the value of true. + + - **`validate_entry_permit_zero_aaguid`** + + `boolean` — is an option that permits a zero'd AAGUID from an attestation statement to automatically pass metadata validations. Generally helpful to use with validate\_entry. + + - **`validate_status`** + + `boolean` — when set to true enables the validation of the attestation statements AAGUID against the desired and undesired lists + + - **`enable_auto_registration`** + + `boolean` — Enable auto registration for WebAuthn + + - **`enable_conditional_login`** + + `boolean` — Allow autofill of passkeys in login page + + - **`rp`** + + `object` + + - **`ids`** + + `array` + + **Items:** + + `string` + + - **`origins`** + + `array` + + **Items:** + + `string` + + - **`show_passkey_button`** + + `boolean` — Show passkey button on login screen + + - **`timeout`** + + `object` + + - **`login`** + + `string`, default: `"\"300s\""` — Login timeout duration + + - **`login_uvd`** + + `string`, default: `"\"300s\""` — Login timeout duration when user verification is discouraged + + - **`registration`** + + `string`, default: `"\"300s\""` — Registration timeout duration + + - **`registration_uvd`** + + `string`, default: `"\"300s\""` — Registration timeout duration when user verification is discouraged + +**Example:** + +```json +{ + "attribute_mapping": { + "additionalProperty": "" + }, + "configuration_type": "MANUAL", + "debug_enabled": true, + "domains": [ + { + "name": "example.com" + } + ], + "enabled": false, + "id": "conn_2123312131125533", + "key_id": "", + "oauth_config": { + "access_type": "offline", + "authorize_uri": "https://youridp.com/service/oauth/authorize", + "client_id": "oauth_client_id", + "client_secret": "oauth_client_secret", + "custom_scope_name": "user_scope", + "pkce_enabled": true, + "prompt": "none", + "redirect_uri": "https://yourapp.com/service/oauth/redirect", + "scopes": [ + "openid", + "profile" + ], + "sync_user_profile_on_login": true, + "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "token_access_type": "offline", + "token_uri": "https://youridp.com/service/oauth/token", + "use_platform_creds": true, + "user_info_uri": "https://youridp.com/service/oauth/userinfo" + }, + "oidc_config": { + "authorize_uri": "https://youridp.com/service/oauth/authorize", + "backchannel_logout_redirect_uri": "https://yourapp.com/sso/v1/oidc/conn_1234/backchannel-logout", + "client_id": "oauth_client_id", + "client_secret": "oauth_client_secret", + "discovery_endpoint": "https://youridp.com/service/oauth/.well-known/openid-configuration", + "idp_logout_required": true, + "issuer": "https://youridp.com/service/oauth", + "jit_provisioning_with_sso_enabled": true, + "jwks_uri": "https://youridp.com/service/oauth/jwks", + "pkce_enabled": true, + "post_logout_redirect_uri": "https://yourapp.com/sso/v1/oidc/conn_1234/logout/callback", + "redirect_uri": "https://yourapp.com/sso/v1/oidc/conn_1234/callback", + "scopes": [ + "openid", + "profile" + ], + "sync_user_profile_on_login": true, + "token_auth_type": "URL_PARAMS", + "token_uri": "https://youridp.com/service/oauth/token", + "user_info_uri": "https://youridp.com/service/oauth/userinfo" + }, + "organization_id": "org_2123312131125533", + "passwordless_config": { + "code_challenge_length": 6, + "code_challenge_type": "NUMERIC", + "enforce_same_browser_origin": true, + "frequency": 1, + "regenerate_passwordless_credentials_on_resend": true, + "type": "LINK", + "validity": 600 + }, + "provider": "OKTA", + "provider_key": "google", + "saml_config": { + "allow_idp_initiated_login": true, + "assertion_encrypted": true, + "certificate_id": "cer_35585423166144613", + "default_redirect_uri": "https://yourapp.com/service/saml/redirect", + "force_authn": true, + "idp_certificates": [ + {} + ], + "idp_entity_id": "https://youridp.com/service/saml", + "idp_metadata_url": "https://youridp.com/service/saml/metadata", + "idp_name_id_format": "EMAIL", + "idp_slo_request_binding": "HTTP_POST", + "idp_slo_required": true, + "idp_slo_url": "https://youridp.com/service/saml/slo", + "idp_sso_request_binding": "HTTP_POST", + "idp_sso_url": "https://youridp.com/service/saml/sso", + "jit_provisioning_with_sso_enabled": true, + "saml_signing_option": "SAML_ONLY_RESPONSE_SIGNING", + "sp_assertion_url": "https://youridp.com/service/saml/assertion", + "sp_entity_id": "https://yourapp.com/service/saml", + "sp_metadata_url": "https://youridp.com/service/saml/metadata", + "sp_slo_url": "https://yourapp.com/sso/v1/saml/conn_1234/slo/callback", + "sync_user_profile_on_login": true, + "ui_button_title": "Login with SSO", + "want_request_signed": true + }, + "static_config": { + "static_config": {} + }, + "status": "IN_PROGRESS", + "test_connection_uri": "https://auth.example.com/test-connection/conn_2123312131125533", + "type": "OIDC", + "webauthn_config": { + "attestation": null, + "authenticator_selection": null, + "authenticators": null, + "enable_auto_registration": true, + "enable_conditional_login": true, + "rp": null, + "show_passkey_button": true, + "timeout": null + } +} +``` + +### connectionsConnectionProvider + +- **Type:**`string` + +**Example:** + +### connectionsConnectionStatus + +- **Type:**`string` + +**Example:** + +### connectionsConnectionType + +- **Type:**`string` + +**Example:** + +### connectionsGetConnectionResponse + +- **Type:**`object` + +* **`connection`** + + `object` — Complete connection details including provider configuration, protocol settings, status, and all metadata. Contains everything needed to understand the connection's current state. + + - **`attribute_mapping`** + + `object` — Maps identity provider attributes to user profile fields. For example, {'email': 'user.mail', 'name': 'user.displayName'}. + + - **`configuration_type`** + + `string`, possible values: `"DISCOVERY", "MANUAL"` — How the connection was configured: DISCOVERY (automatic configuration) or MANUAL (administrator configured) + + - **`debug_enabled`** + + `boolean` — Enables testing mode that allows non-HTTPS endpoints. Should only be enabled in development environments, never in production. + + - **`domains`** + + `array` — Domain associated with this connection, used for domain-based authentication flows. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the domain was first created. + + - **`domain`** + + `string` — The business domain name that was configured for allowed email domain functionality (e.g., company.com, subdomain.company.com). + + - **`domain_type`** + + `object` + + - **`environment_id`** + + `string` — The environment ID where this domain is configured. + + - **`id`** + + `string` — Scalekit-generated unique identifier for this domain record. + + - **`organization_id`** + + `string` — The organization to which the domain belongs. + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the domain was last updated. + + - **`verification_method`** + + `string`, possible values: `"ADMIN", "DNS", "NOT_APPLICABLE"` — Method that determines how domain ownership is verified. - ADMIN: domain is marked verified without DNS validation, typically by an admin. - DNS: domain must be verified by adding a TXT record to your DNS configuration. - NOT\_APPLICABLE: verification does not apply to this domain type. + + - **`verification_status`** + + `string`, possible values: `"PENDING", "VERIFIED", "FAILED", "AUTO_VERIFIED"` — Verification status of the domain. - PENDING: DNS TXT record has not been validated yet. - VERIFIED: domain confirmed via DNS TXT record validation or admin approval. - AUTO\_VERIFIED: domain verified automatically without DNS changes. - FAILED: DNS TXT record was not validated within the verification window. + + - **`enabled`** + + `boolean` — Controls whether users can sign in using this connection. When false, the connection exists but cannot be used for authentication. + + - **`id`** + + `string` — Unique identifier for this connection. Used in API calls to reference this specific connection. + + - **`key_id`** + + `string` — Alternative identifier for this connection, typically used in frontend applications or URLs. + + - **`oauth_config`** + + `object` — Configuration details for OAuth connections. Present only when type is OAUTH. + + - **`access_type`** + + `string` — Access Type + + - **`authorize_uri`** + + `string` — Authorize URI + + - **`client_id`** + + `string` — Client ID + + - **`client_secret`** + + `string` — Client Secret + + - **`custom_scope_name`** + + `string` — Custom Scope Name + + - **`pkce_enabled`** + + `boolean` — PKCE Enabled + + - **`prompt`** + + `string` — Prompt for the user + + - **`redirect_uri`** + + `string` — Redirect URI + + - **`scopes`** + + `array` — OIDC Scopes + + **Items:** + + `string` + + - **`sync_user_profile_on_login`** + + `boolean` — Indicates whether user profiles should be synchronized with the identity provider upon each log-in. + + - **`tenant_id`** + + `string` — Microsoft Entra tenant ID. Required when using a single-tenant or multi-tenant app registered in Microsoft Entra. Leave empty to use the common endpoint. + + - **`token_access_type`** + + `string` — Token Access Type + + - **`token_uri`** + + `string` — Token URI + + - **`use_platform_creds`** + + `boolean` — Use Scalekit credentials + + - **`user_info_uri`** + + `string` — User Info URI + + - **`oidc_config`** + + `object` — Configuration details for OpenID Connect (OIDC) connections. Present only when type is OIDC. + + - **`authorize_uri`** + + `string` — Authorize URI + + - **`backchannel_logout_redirect_uri`** + + `string` — backchannel logout redirect uri where idp sends logout\_token + + - **`client_id`** + + `string` — Client ID + + - **`client_secret`** + + `string` — Client Secret + + - **`discovery_endpoint`** + + `string` — Discovery Endpoint + + - **`idp_logout_required`** + + `boolean` — Enable IDP logout + + - **`issuer`** + + `string` — Issuer URL + + - **`jit_provisioning_with_sso_enabled`** + + `boolean` — Indicates if Just In Time user provisioning is enabled for the connection + + - **`jwks_uri`** + + `string` — JWKS URI + + - **`pkce_enabled`** + + `boolean` — PKCE Enabled + + - **`post_logout_redirect_uri`** + + `string` — post logout redirect uri + + - **`redirect_uri`** + + `string` — Redirect URI + + - **`scopes`** + + `array` — OIDC Scopes + + **Items:** + + `string`, possible values: `"openid", "profile", "email", "address", "phone"` + + - **`sync_user_profile_on_login`** + + `boolean` — Indicates whether user profiles should be synchronized with the identity provider upon each log-in. + + - **`token_auth_type`** + + `string`, possible values: `"URL_PARAMS", "BASIC_AUTH"` — Token Auth Type + + - **`token_uri`** + + `string` — Token URI + + - **`user_info_uri`** + + `string` — User Info URI + + - **`organization_id`** + + `string` — Identifier of the organization that owns this connection. Connections are typically scoped to a single organization. + + - **`passwordless_config`** + + `object` — Configuration details for Magic Link authentication. Present only when type is MAGIC\_LINK. + + - **`code_challenge_length`** + + `integer`, format: `int64` — Code Challenge Length + + - **`code_challenge_type`** + + `string`, possible values: `"NUMERIC", "ALPHANUMERIC"` — Code Challenge Type + + - **`enforce_same_browser_origin`** + + `boolean` — Enforce Same Browser Origin + + - **`frequency`** + + `integer`, format: `int64` — Link Frequency + + - **`regenerate_passwordless_credentials_on_resend`** + + `boolean` — Regenerate the + + - **`type`** + + `string`, possible values: `"LINK", "OTP", "LINK_OTP"` — Passwordless Type + + - **`validity`** + + `integer`, format: `int64` — Link Validity in Seconds + + - **`provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Identity provider service that handles authentication (such as OKTA, Google, Azure AD, or a custom provider) + + - **`provider_key`** + + `string` — Key ID of the identity provider service that handles authentication + + - **`saml_config`** + + `object` — Configuration details for SAML connections. Present only when type is SAML. + + - **`allow_idp_initiated_login`** + + `boolean` — Allow IDP Initiated Login + + - **`assertion_encrypted`** + + `boolean` — Assertion Encrypted + + - **`certificate_id`** + + `string` — Certificate ID + + - **`default_redirect_uri`** + + `string` — Default Redirect URI + + - **`force_authn`** + + `boolean` — Force Authn + + - **`idp_certificates`** + + `array` — IDP Certificates + + **Items:** + + - **`certificate`** + + `string` — IDP Certificate + + - **`create_time`** + + `string`, format: `date-time` — Certificate Creation Time + + - **`expiry_time`** + + `string`, format: `date-time` — Certificate Expiry Time + + - **`id`** + + `string` — Certificate ID + + - **`issuer`** + + `string` — Certificate Issuer + + - **`idp_entity_id`** + + `string` — IDP Entity ID + + - **`idp_metadata_url`** + + `string` — IDP Metadata URL + + - **`idp_name_id_format`** + + `string`, possible values: `"UNSPECIFIED", "EMAIL", "TRANSIENT", "PERSISTENT"` — IDP Name ID Format + + - **`idp_slo_request_binding`** + + `string`, possible values: `"HTTP_POST", "HTTP_REDIRECT"` — IDP SLO Request Binding + + - **`idp_slo_required`** + + `boolean` — Enable IDP logout + + - **`idp_slo_url`** + + `string` — IDP SLO URL + + - **`idp_sso_request_binding`** + + `string`, possible values: `"HTTP_POST", "HTTP_REDIRECT"` — IDP SSO Request Binding + + - **`idp_sso_url`** + + `string` — IDP SSO URL + + - **`jit_provisioning_with_sso_enabled`** + + `boolean` — Indicates if Just In Time user provisioning is enabled for the connection + + - **`saml_signing_option`** + + `string`, possible values: `"NO_SIGNING", "SAML_ONLY_RESPONSE_SIGNING", "SAML_ONLY_ASSERTION_SIGNING", "SAML_RESPONSE_ASSERTION_SIGNING", "SAML_RESPONSE_OR_ASSERTION_SIGNING"` — SAML Signing Option + + - **`sp_assertion_url`** + + `string` — SP Assertion URL + + - **`sp_entity_id`** + + `string` — SP Entity ID + + - **`sp_metadata_url`** + + `string` — SP Metadata URL + + - **`sp_slo_url`** + + `string` — Service Provider SLO url + + - **`sync_user_profile_on_login`** + + `boolean` — Indicates whether user profiles should be synchronized with the identity provider upon each log-in. + + - **`ui_button_title`** + + `string` — UI Button Title + + - **`want_request_signed`** + + `boolean` — Want Request Signed + + - **`static_config`** + + `object` — Static configuration for custom connections. Present only when type is BASIC, BEARER, API\_KEY, or custom. + + - **`static_config`** + + `object` + + - **`status`** + + `string`, possible values: `"DRAFT", "IN_PROGRESS", "COMPLETED"` — Current configuration status of the connection. Possible values include IN\_PROGRESS, CONFIGURED, and ERROR. + + - **`test_connection_uri`** + + `string` — URI that can be used to test this connection. Visit this URL to verify the connection works correctly. + + - **`type`** + + `string`, possible values: `"OIDC", "SAML", "PASSWORD", "OAUTH", "PASSWORDLESS", "BASIC", "BEARER", "API_KEY", "WEBAUTHN"` — Authentication protocol used by this connection. Can be OIDC (OpenID Connect), SAML, OAUTH, or MAGIC\_LINK. + + - **`webauthn_config`** + + `object` — Configuration details for WebAuthn (passkeys). Present only when type is WEBAUTHN. + + - **`attestation`** + + `object` + + - **`conveyance_preference`** + + `string` + + - **`enterprise_approved_ids`** + + `array` + + **Items:** + + `string` + + - **`authenticator_selection`** + + `object` + + - **`authenticator_attachment`** + + `string` + + - **`user_verification`** + + `string` + + - **`authenticators`** + + `object` + + - **`desired_authenticator_status`** + + `array` — provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate\_status set to true. + + **Items:** + + `string`, default: `"[]"` + + - **`undesired_authenticator_status`** + + `array` — provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate\_status set to true. + + **Items:** + + `string`, default: `"['ATTESTATION_KEY_COMPROMISE', 'USER_VERIFICATION_BYPASS', 'USER_KEY_REMOTE_COMPROMISE', 'USER_KEY_PHYSICAL_COMPROMISE', 'REVOKED']"` + + - **`validate_anchors`** + + `boolean` — when set to true enables the validation of the attestation statement against the trust anchor from the metadata statement. + + - **`validate_attestation_type`** + + `boolean` — when set to true enables the validation of the attestation statements type against the known types the authenticator can produce. + + - **`validate_entry`** + + `boolean` — requires that the provided metadata has an entry for the given authenticator to be considered valid. By default an AAGUID which has a zero value should fail validation if validate\_entry\_permit\_zero\_aaguid is not provided with the value of true. + + - **`validate_entry_permit_zero_aaguid`** + + `boolean` — is an option that permits a zero'd AAGUID from an attestation statement to automatically pass metadata validations. Generally helpful to use with validate\_entry. + + - **`validate_status`** + + `boolean` — when set to true enables the validation of the attestation statements AAGUID against the desired and undesired lists + + - **`enable_auto_registration`** + + `boolean` — Enable auto registration for WebAuthn + + - **`enable_conditional_login`** + + `boolean` — Allow autofill of passkeys in login page + + - **`rp`** + + `object` + + - **`ids`** + + `array` + + **Items:** + + `string` + + - **`origins`** + + `array` + + **Items:** + + `string` + + - **`show_passkey_button`** + + `boolean` — Show passkey button on login screen + + - **`timeout`** + + `object` + + - **`login`** + + `string`, default: `"\"300s\""` — Login timeout duration + + - **`login_uvd`** + + `string`, default: `"\"300s\""` — Login timeout duration when user verification is discouraged + + - **`registration`** + + `string`, default: `"\"300s\""` — Registration timeout duration + + - **`registration_uvd`** + + `string`, default: `"\"300s\""` — Registration timeout duration when user verification is discouraged + +**Example:** + +```json +{ + "connection": { + "attribute_mapping": { + "additionalProperty": "" + }, + "configuration_type": "MANUAL", + "debug_enabled": true, + "domains": [ + { + "name": "example.com" + } + ], + "enabled": false, + "id": "conn_2123312131125533", + "key_id": "", + "oauth_config": null, + "oidc_config": null, + "organization_id": "org_2123312131125533", + "passwordless_config": null, + "provider": "OKTA", + "provider_key": "google", + "saml_config": null, + "static_config": null, + "status": "IN_PROGRESS", + "test_connection_uri": "https://auth.example.com/test-connection/conn_2123312131125533", + "type": "OIDC", + "webauthn_config": null + } +} +``` + +### connectionsIDPCertificate + +- **Type:**`object` + +* **`certificate`** + + `string` — IDP Certificate + +* **`create_time`** + + `string`, format: `date-time` — Certificate Creation Time + +* **`expiry_time`** + + `string`, format: `date-time` — Certificate Expiry Time + +* **`id`** + + `string` — Certificate ID + +* **`issuer`** + + `string` — Certificate Issuer + +**Example:** + +```json +{ + "certificate": "", + "create_time": "2021-09-01T00:00:00Z", + "expiry_time": "2021-09-01T00:00:00Z", + "id": "cert_123123123123", + "issuer": "https://youridp.com/service/saml" +} +``` + +### connectionsListConnection + +- **Type:**`object` + +* **`domains`** + + `array` — List of domains configured with this connection + + **Items:** + + `string` + +* **`enabled`** + + `boolean` — Whether the connection is currently active for organization users + +* **`id`** + + `string` — Unique identifier of the connection + +* **`key_id`** + + `string` — Alternative identifier for this connection, typically used in frontend applications or URLs + +* **`organization_id`** + + `string` — Unique identifier of the organization that owns this connection + +* **`organization_name`** + + `string` — Name of the organization of the connection + +* **`provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Identity provider type (e.g., OKTA, Google, Azure AD) + +* **`provider_key`** + + `string` — Key ID of the identity provider service that handles authentication + +* **`status`** + + `string`, possible values: `"DRAFT", "IN_PROGRESS", "COMPLETED"` — Current configuration status of the connection + +* **`type`** + + `string`, possible values: `"OIDC", "SAML", "PASSWORD", "OAUTH", "PASSWORDLESS", "BASIC", "BEARER", "API_KEY", "WEBAUTHN"` — Authentication protocol used by the connection + +**Example:** + +```json +{ + "domains": [ + "yourapp.com", + "yourworkspace.com" + ], + "enabled": false, + "id": "conn_2123312131125533", + "key_id": "conn_2123312131125533", + "organization_id": "org_2123312131125533", + "organization_name": "Your Organization", + "provider": "CUSTOM", + "provider_key": "google", + "status": "IN_PROGRESS", + "type": "OIDC" +} +``` + +### connectionsListConnectionsResponse + +- **Type:**`object` + +* **`connections`** + + `array` — List of connections matching the request criteria + + **Items:** + + - **`domains`** + + `array` — List of domains configured with this connection + + **Items:** + + `string` + + - **`enabled`** + + `boolean` — Whether the connection is currently active for organization users + + - **`id`** + + `string` — Unique identifier of the connection + + - **`key_id`** + + `string` — Alternative identifier for this connection, typically used in frontend applications or URLs + + - **`organization_id`** + + `string` — Unique identifier of the organization that owns this connection + + - **`organization_name`** + + `string` — Name of the organization of the connection + + - **`provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Identity provider type (e.g., OKTA, Google, Azure AD) + + - **`provider_key`** + + `string` — Key ID of the identity provider service that handles authentication + + - **`status`** + + `string`, possible values: `"DRAFT", "IN_PROGRESS", "COMPLETED"` — Current configuration status of the connection + + - **`type`** + + `string`, possible values: `"OIDC", "SAML", "PASSWORD", "OAUTH", "PASSWORDLESS", "BASIC", "BEARER", "API_KEY", "WEBAUTHN"` — Authentication protocol used by the connection + +**Example:** + +```json +{ + "connections": [ + { + "domains": [ + "yourapp.com", + "yourworkspace.com" + ], + "enabled": false, + "id": "conn_2123312131125533", + "key_id": "conn_2123312131125533", + "organization_id": "org_2123312131125533", + "organization_name": "Your Organization", + "provider": "CUSTOM", + "provider_key": "google", + "status": "IN_PROGRESS", + "type": "OIDC" + } + ] +} +``` + +### connectionsNameIdFormat + +- **Type:**`string` + +**Example:** + +### connectionsOAuthConnectionConfig + +- **Type:**`object` + +* **`access_type`** + + `string` — Access Type + +* **`authorize_uri`** + + `string` — Authorize URI + +* **`client_id`** + + `string` — Client ID + +* **`client_secret`** + + `string` — Client Secret + +* **`custom_scope_name`** + + `string` — Custom Scope Name + +* **`pkce_enabled`** + + `boolean` — PKCE Enabled + +* **`prompt`** + + `string` — Prompt for the user + +* **`redirect_uri`** + + `string` — Redirect URI + +* **`scopes`** + + `array` — OIDC Scopes + + **Items:** + + `string` + +* **`sync_user_profile_on_login`** + + `boolean` — Indicates whether user profiles should be synchronized with the identity provider upon each log-in. + +* **`tenant_id`** + + `string` — Microsoft Entra tenant ID. Required when using a single-tenant or multi-tenant app registered in Microsoft Entra. Leave empty to use the common endpoint. + +* **`token_access_type`** + + `string` — Token Access Type + +* **`token_uri`** + + `string` — Token URI + +* **`use_platform_creds`** + + `boolean` — Use Scalekit credentials + +* **`user_info_uri`** + + `string` — User Info URI + +**Example:** + +```json +{ + "access_type": "offline", + "authorize_uri": "https://youridp.com/service/oauth/authorize", + "client_id": "oauth_client_id", + "client_secret": "oauth_client_secret", + "custom_scope_name": "user_scope", + "pkce_enabled": true, + "prompt": "none", + "redirect_uri": "https://yourapp.com/service/oauth/redirect", + "scopes": [ + "openid", + "profile" + ], + "sync_user_profile_on_login": true, + "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "token_access_type": "offline", + "token_uri": "https://youridp.com/service/oauth/token", + "use_platform_creds": true, + "user_info_uri": "https://youridp.com/service/oauth/userinfo" +} +``` + +### connectionsOIDCConnectionConfig + +- **Type:**`object` + +* **`authorize_uri`** + + `string` — Authorize URI + +* **`backchannel_logout_redirect_uri`** + + `string` — backchannel logout redirect uri where idp sends logout\_token + +* **`client_id`** + + `string` — Client ID + +* **`client_secret`** + + `string` — Client Secret + +* **`discovery_endpoint`** + + `string` — Discovery Endpoint + +* **`idp_logout_required`** + + `boolean` — Enable IDP logout + +* **`issuer`** + + `string` — Issuer URL + +* **`jit_provisioning_with_sso_enabled`** + + `boolean` — Indicates if Just In Time user provisioning is enabled for the connection + +* **`jwks_uri`** + + `string` — JWKS URI + +* **`pkce_enabled`** + + `boolean` — PKCE Enabled + +* **`post_logout_redirect_uri`** + + `string` — post logout redirect uri + +* **`redirect_uri`** + + `string` — Redirect URI + +* **`scopes`** + + `array` — OIDC Scopes + + **Items:** + + `string`, possible values: `"openid", "profile", "email", "address", "phone"` + +* **`sync_user_profile_on_login`** + + `boolean` — Indicates whether user profiles should be synchronized with the identity provider upon each log-in. + +* **`token_auth_type`** + + `string`, possible values: `"URL_PARAMS", "BASIC_AUTH"` — Token Auth Type + +* **`token_uri`** + + `string` — Token URI + +* **`user_info_uri`** + + `string` — User Info URI + +**Example:** + +```json +{ + "authorize_uri": "https://youridp.com/service/oauth/authorize", + "backchannel_logout_redirect_uri": "https://yourapp.com/sso/v1/oidc/conn_1234/backchannel-logout", + "client_id": "oauth_client_id", + "client_secret": "oauth_client_secret", + "discovery_endpoint": "https://youridp.com/service/oauth/.well-known/openid-configuration", + "idp_logout_required": true, + "issuer": "https://youridp.com/service/oauth", + "jit_provisioning_with_sso_enabled": true, + "jwks_uri": "https://youridp.com/service/oauth/jwks", + "pkce_enabled": true, + "post_logout_redirect_uri": "https://yourapp.com/sso/v1/oidc/conn_1234/logout/callback", + "redirect_uri": "https://yourapp.com/sso/v1/oidc/conn_1234/callback", + "scopes": [ + "openid", + "profile" + ], + "sync_user_profile_on_login": true, + "token_auth_type": "URL_PARAMS", + "token_uri": "https://youridp.com/service/oauth/token", + "user_info_uri": "https://youridp.com/service/oauth/userinfo" +} +``` + +### connectionsOIDCScope + +- **Type:**`string` + +**Example:** + +### connectionsPasswordLessConfig + +- **Type:**`object` + +* **`code_challenge_length`** + + `integer`, format: `int64` — Code Challenge Length + +* **`code_challenge_type`** + + `string`, possible values: `"NUMERIC", "ALPHANUMERIC"` — Code Challenge Type + +* **`enforce_same_browser_origin`** + + `boolean` — Enforce Same Browser Origin + +* **`frequency`** + + `integer`, format: `int64` — Link Frequency + +* **`regenerate_passwordless_credentials_on_resend`** + + `boolean` — Regenerate the + +* **`type`** + + `string`, possible values: `"LINK", "OTP", "LINK_OTP"` — Passwordless Type + +* **`validity`** + + `integer`, format: `int64` — Link Validity in Seconds + +**Example:** + +```json +{ + "code_challenge_length": 6, + "code_challenge_type": "NUMERIC", + "enforce_same_browser_origin": true, + "frequency": 1, + "regenerate_passwordless_credentials_on_resend": true, + "type": "LINK", + "validity": 600 +} +``` + +### connectionsPasswordlessType + +- **Type:**`string` + +**Example:** + +### connectionsRequestBinding + +- **Type:**`string` + +**Example:** + +### connectionsSAMLConnectionConfigResponse + +- **Type:**`object` + +* **`allow_idp_initiated_login`** + + `boolean` — Allow IDP Initiated Login + +* **`assertion_encrypted`** + + `boolean` — Assertion Encrypted + +* **`certificate_id`** + + `string` — Certificate ID + +* **`default_redirect_uri`** + + `string` — Default Redirect URI + +* **`force_authn`** + + `boolean` — Force Authn + +* **`idp_certificates`** + + `array` — IDP Certificates + + **Items:** + + - **`certificate`** + + `string` — IDP Certificate + + - **`create_time`** + + `string`, format: `date-time` — Certificate Creation Time + + - **`expiry_time`** + + `string`, format: `date-time` — Certificate Expiry Time + + - **`id`** + + `string` — Certificate ID + + - **`issuer`** + + `string` — Certificate Issuer + +* **`idp_entity_id`** + + `string` — IDP Entity ID + +* **`idp_metadata_url`** + + `string` — IDP Metadata URL + +* **`idp_name_id_format`** + + `string`, possible values: `"UNSPECIFIED", "EMAIL", "TRANSIENT", "PERSISTENT"` — IDP Name ID Format + +* **`idp_slo_request_binding`** + + `string`, possible values: `"HTTP_POST", "HTTP_REDIRECT"` — IDP SLO Request Binding + +* **`idp_slo_required`** + + `boolean` — Enable IDP logout + +* **`idp_slo_url`** + + `string` — IDP SLO URL + +* **`idp_sso_request_binding`** + + `string`, possible values: `"HTTP_POST", "HTTP_REDIRECT"` — IDP SSO Request Binding + +* **`idp_sso_url`** + + `string` — IDP SSO URL + +* **`jit_provisioning_with_sso_enabled`** + + `boolean` — Indicates if Just In Time user provisioning is enabled for the connection + +* **`saml_signing_option`** + + `string`, possible values: `"NO_SIGNING", "SAML_ONLY_RESPONSE_SIGNING", "SAML_ONLY_ASSERTION_SIGNING", "SAML_RESPONSE_ASSERTION_SIGNING", "SAML_RESPONSE_OR_ASSERTION_SIGNING"` — SAML Signing Option + +* **`sp_assertion_url`** + + `string` — SP Assertion URL + +* **`sp_entity_id`** + + `string` — SP Entity ID + +* **`sp_metadata_url`** + + `string` — SP Metadata URL + +* **`sp_slo_url`** + + `string` — Service Provider SLO url + +* **`sync_user_profile_on_login`** + + `boolean` — Indicates whether user profiles should be synchronized with the identity provider upon each log-in. + +* **`ui_button_title`** + + `string` — UI Button Title + +* **`want_request_signed`** + + `boolean` — Want Request Signed + +**Example:** + +```json +{ + "allow_idp_initiated_login": true, + "assertion_encrypted": true, + "certificate_id": "cer_35585423166144613", + "default_redirect_uri": "https://yourapp.com/service/saml/redirect", + "force_authn": true, + "idp_certificates": [ + { + "certificate": "", + "create_time": "2021-09-01T00:00:00Z", + "expiry_time": "2021-09-01T00:00:00Z", + "id": "cert_123123123123", + "issuer": "https://youridp.com/service/saml" + } + ], + "idp_entity_id": "https://youridp.com/service/saml", + "idp_metadata_url": "https://youridp.com/service/saml/metadata", + "idp_name_id_format": "EMAIL", + "idp_slo_request_binding": "HTTP_POST", + "idp_slo_required": true, + "idp_slo_url": "https://youridp.com/service/saml/slo", + "idp_sso_request_binding": "HTTP_POST", + "idp_sso_url": "https://youridp.com/service/saml/sso", + "jit_provisioning_with_sso_enabled": true, + "saml_signing_option": "SAML_ONLY_RESPONSE_SIGNING", + "sp_assertion_url": "https://youridp.com/service/saml/assertion", + "sp_entity_id": "https://yourapp.com/service/saml", + "sp_metadata_url": "https://youridp.com/service/saml/metadata", + "sp_slo_url": "https://yourapp.com/sso/v1/saml/conn_1234/slo/callback", + "sync_user_profile_on_login": true, + "ui_button_title": "Login with SSO", + "want_request_signed": true +} +``` + +### enums all + +- **Type:**`string` + +**Example:** + +### connectionsStaticAuthConfig + +- **Type:**`object` + +* **`static_config`** + + `object` + +**Example:** + +```json +{ + "static_config": {} +} +``` + +### connectionsToggleConnectionResponse + +- **Type:**`object` + +* **`enabled`** + + `boolean` — Current state of the connection after the operation. True means the connection is now enabled and can be used for authentication. + +* **`error_message`** + + `string` — Error message if the operation fails + +**Example:** + +```json +{ + "enabled": true, + "error_message": "placeholder" +} +``` + +### connectionsTokenAuthType + +- **Type:**`string` + +**Example:** + +### WebAuthConfiguration defines WebAuthn (passkeys) configuration limited to RP and Attestation + +- **Type:**`object` + +* **`attestation`** + + `object` + + - **`conveyance_preference`** + + `string` + + - **`enterprise_approved_ids`** + + `array` + + **Items:** + + `string` + +* **`authenticator_selection`** + + `object` + + - **`authenticator_attachment`** + + `string` + + - **`user_verification`** + + `string` + +* **`authenticators`** + + `object` + + - **`desired_authenticator_status`** + + `array` — provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate\_status set to true. + + **Items:** + + `string`, default: `"[]"` + + - **`undesired_authenticator_status`** + + `array` — provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate\_status set to true. + + **Items:** + + `string`, default: `"['ATTESTATION_KEY_COMPROMISE', 'USER_VERIFICATION_BYPASS', 'USER_KEY_REMOTE_COMPROMISE', 'USER_KEY_PHYSICAL_COMPROMISE', 'REVOKED']"` + + - **`validate_anchors`** + + `boolean` — when set to true enables the validation of the attestation statement against the trust anchor from the metadata statement. + + - **`validate_attestation_type`** + + `boolean` — when set to true enables the validation of the attestation statements type against the known types the authenticator can produce. + + - **`validate_entry`** + + `boolean` — requires that the provided metadata has an entry for the given authenticator to be considered valid. By default an AAGUID which has a zero value should fail validation if validate\_entry\_permit\_zero\_aaguid is not provided with the value of true. + + - **`validate_entry_permit_zero_aaguid`** + + `boolean` — is an option that permits a zero'd AAGUID from an attestation statement to automatically pass metadata validations. Generally helpful to use with validate\_entry. + + - **`validate_status`** + + `boolean` — when set to true enables the validation of the attestation statements AAGUID against the desired and undesired lists + +* **`enable_auto_registration`** + + `boolean` — Enable auto registration for WebAuthn + +* **`enable_conditional_login`** + + `boolean` — Allow autofill of passkeys in login page + +* **`rp`** + + `object` + + - **`ids`** + + `array` + + **Items:** + + `string` + + - **`origins`** + + `array` + + **Items:** + + `string` + +* **`show_passkey_button`** + + `boolean` — Show passkey button on login screen + +* **`timeout`** + + `object` + + - **`login`** + + `string`, default: `"\"300s\""` — Login timeout duration + + - **`login_uvd`** + + `string`, default: `"\"300s\""` — Login timeout duration when user verification is discouraged + + - **`registration`** + + `string`, default: `"\"300s\""` — Registration timeout duration + + - **`registration_uvd`** + + `string`, default: `"\"300s\""` — Registration timeout duration when user verification is discouraged + +**Example:** + +```json +{ + "attestation": { + "conveyance_preference": "", + "enterprise_approved_ids": [ + "" + ] + }, + "authenticator_selection": { + "authenticator_attachment": "", + "user_verification": "" + }, + "authenticators": { + "desired_authenticator_status": [ + "[]" + ], + "undesired_authenticator_status": [ + "['ATTESTATION_KEY_COMPROMISE', 'USER_VERIFICATION_BYPASS', 'USER_KEY_REMOTE_COMPROMISE', 'USER_KEY_PHYSICAL_COMPROMISE', 'REVOKED']" + ], + "validate_anchors": true, + "validate_attestation_type": true, + "validate_entry": true, + "validate_entry_permit_zero_aaguid": true, + "validate_status": true + }, + "enable_auto_registration": true, + "enable_conditional_login": true, + "rp": { + "ids": [ + "" + ], + "origins": [ + "" + ] + }, + "show_passkey_button": true, + "timeout": { + "login": "\"300s\"", + "login_uvd": "\"300s\"", + "registration": "\"300s\"", + "registration_uvd": "\"300s\"" + } +} +``` + +### directoriesAttributeMapping + +- **Type:**`object` + +* **`key`** + + `string` + +* **`map_to`** + + `string` + +**Example:** + +```json +{ + "key": "", + "map_to": "" +} +``` + +### directoriesAttributeMappings + +- **Type:**`object` + +* **`attributes`** + + `array` + + **Items:** + + - **`key`** + + `string` + + - **`map_to`** + + `string` + +**Example:** + +```json +{ + "attributes": [ + { + "key": "", + "map_to": "" + } + ] +} +``` + +### directoriesDirectory + +- **Type:**`object` + +* **`attribute_mappings`** + + `object` — Mappings between directory attributes and Scalekit user and group attributes + + - **`attributes`** + + `array` + + **Items:** + + - **`key`** + + `string` + + - **`map_to`** + + `string` + +* **`directory_endpoint`** + + `string` — The endpoint URL generated by Scalekit for synchronizing users and groups from the Directory Provider + +* **`directory_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "JUMPCLOUD", "PING_IDENTITY"` — Identity provider connected to this directory + +* **`directory_type`** + + `string`, possible values: `"SCIM", "LDAP", "POLL"` — Type of the directory, indicating the protocol or standard used for synchronization + +* **`email`** + + `string` — Email Id associated with Directory whose access will be used for polling + +* **`enabled`** + + `boolean` — Indicates whether the directory is currently enabled and actively synchronizing users and groups + +* **`groups_tracked`** + + `string` — It indicates if all groups are tracked or select groups are tracked + +* **`id`** + + `string` — Unique identifier of the directory + +* **`last_synced_at`** + + `string`, format: `date-time` — Timestamp of the last successful synchronization of users and groups from the Directory Provider + +* **`name`** + + `string` — Name of the directory, typically representing the connected Directory provider + +* **`organization_id`** + + `string` — Unique identifier of the organization to which the directory belongs + +* **`role_assignments`** + + `object` — Role assignments associated with the directory, defining group based role assignments + + - **`assignments`** + + `array` + + **Items:** + + - **`group_id`** + + `string` — group ID for the role mapping + + - **`role_name`** + + `string` + +* **`secrets`** + + `array` — List of secrets used for authenticating and synchronizing with the Directory Provider + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Creation Time + + - **`directory_id`** + + `string` — Directory ID + + - **`expire_time`** + + `string`, format: `date-time` — Expiry Time + + - **`id`** + + `string` + + - **`last_used_time`** + + `string`, format: `date-time` — Last Used Time + + - **`secret_suffix`** + + `string` — Secret Suffix + + - **`status`** + + `string`, possible values: `"INACTIVE"` — Secret Status + +* **`stats`** + + `object` — Statistics and metrics related to the directory, such as synchronization status and error counts + + - **`group_updated_at`** + + `string`, format: `date-time` — Max time of Group Updated At for Directory + + - **`total_groups`** + + `integer`, format: `int32` — Total Groups in the Directory + + - **`total_users`** + + `integer`, format: `int32` — Total Users in the Directory + + - **`user_updated_at`** + + `string`, format: `date-time` — Max time of User Updated At for Directory + +* **`status`** + + `string` — Directory Status + +* **`total_groups`** + + `integer`, format: `int32` — Total number of groups in the directory + +* **`total_users`** + + `integer`, format: `int32` — Total number of users in the directory + +**Example:** + +```json +{ + "attribute_mappings": { + "attributes": [ + {} + ] + }, + "directory_endpoint": "https://yourapp.scalekit.com/api/v1/directoies/dir_123212312/scim/v2", + "directory_provider": "OKTA", + "directory_type": "SCIM", + "email": "john.doe@scalekit.cloud", + "enabled": true, + "groups_tracked": "ALL", + "id": "dir_121312434123312", + "last_synced_at": "2024-10-01T00:00:00Z", + "name": "Azure AD", + "organization_id": "org_121312434123312", + "role_assignments": { + "assignments": [ + {} + ] + }, + "secrets": [ + { + "create_time": "2024-10-01T00:00:00Z", + "directory_id": "dir_12362474900684814", + "expire_time": "2025-10-01T00:00:00Z", + "id": "", + "last_used_time": "2024-10-01T00:00:00Z", + "secret_suffix": "Nzg5", + "status": "INACTIVE" + } + ], + "stats": { + "group_updated_at": "2024-10-01T00:00:00Z", + "total_groups": 10, + "total_users": 10, + "user_updated_at": "2024-10-01T00:00:00Z" + }, + "status": "IN_PROGRESS", + "total_groups": 10, + "total_users": 10 +} +``` + +### directoriesDirectoryGroup + +- **Type:**`object` + +* **`display_name`** + + `string` — Display Name + +* **`group_detail`** + + `object` — Complete Group Details Payload + +* **`id`** + + `string` — Group ID + +* **`total_users`** + + `integer`, format: `int32` — Total Users in the Group + +* **`updated_at`** + + `string`, format: `date-time` — Updated At + +**Example:** + +```json +{ + "display_name": "Admins", + "group_detail": {}, + "id": "dirgroup_121312434123312", + "total_users": 10, + "updated_at": "2024-10-01T00:00:00Z" +} +``` + +### directoriesDirectoryProvider + +- **Type:**`string` + +**Example:** + +### directoriesDirectoryType + +- **Type:**`string` + +**Example:** + +### directoriesDirectoryUser + +- **Type:**`object` + +* **`email`** + + `string` — Email + +* **`emails`** + + `array` — Emails + + **Items:** + + `string` + +* **`family_name`** + + `string` — Last Name + +* **`given_name`** + + `string` — First Name + +* **`groups`** + + `array` — Groups + + **Items:** + + - **`display_name`** + + `string` — Display Name + + - **`group_detail`** + + `object` — Complete Group Details Payload + + - **`id`** + + `string` — Group ID + + - **`total_users`** + + `integer`, format: `int32` — Total Users in the Group + + - **`updated_at`** + + `string`, format: `date-time` — Updated At + +* **`id`** + + `string` — User ID + +* **`preferred_username`** + + `string` — Preferred Username + +* **`updated_at`** + + `string`, format: `date-time` — Updated At + +* **`user_detail`** + + `object` — Complete User Details Payload + +**Example:** + +```json +{ + "email": "johndoe", + "emails": [ + "" + ], + "family_name": "Doe", + "given_name": "John", + "groups": [ + { + "display_name": "Admins", + "group_detail": {}, + "id": "dirgroup_121312434123312", + "total_users": 10, + "updated_at": "2024-10-01T00:00:00Z" + } + ], + "id": "diruser_121312434123312", + "preferred_username": "johndoe", + "updated_at": "2024-10-01T00:00:00Z", + "user_detail": {} +} +``` + +### directoriesGetDirectoryResponse + +- **Type:**`object` + +* **`directory`** + + `object` — Detailed information about the requested directory + + - **`attribute_mappings`** + + `object` — Mappings between directory attributes and Scalekit user and group attributes + + - **`attributes`** + + `array` + + **Items:** + + - **`key`** + + `string` + + - **`map_to`** + + `string` + + - **`directory_endpoint`** + + `string` — The endpoint URL generated by Scalekit for synchronizing users and groups from the Directory Provider + + - **`directory_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "JUMPCLOUD", "PING_IDENTITY"` — Identity provider connected to this directory + + - **`directory_type`** + + `string`, possible values: `"SCIM", "LDAP", "POLL"` — Type of the directory, indicating the protocol or standard used for synchronization + + - **`email`** + + `string` — Email Id associated with Directory whose access will be used for polling + + - **`enabled`** + + `boolean` — Indicates whether the directory is currently enabled and actively synchronizing users and groups + + - **`groups_tracked`** + + `string` — It indicates if all groups are tracked or select groups are tracked + + - **`id`** + + `string` — Unique identifier of the directory + + - **`last_synced_at`** + + `string`, format: `date-time` — Timestamp of the last successful synchronization of users and groups from the Directory Provider + + - **`name`** + + `string` — Name of the directory, typically representing the connected Directory provider + + - **`organization_id`** + + `string` — Unique identifier of the organization to which the directory belongs + + - **`role_assignments`** + + `object` — Role assignments associated with the directory, defining group based role assignments + + - **`assignments`** + + `array` + + **Items:** + + - **`group_id`** + + `string` — group ID for the role mapping + + - **`role_name`** + + `string` + + - **`secrets`** + + `array` — List of secrets used for authenticating and synchronizing with the Directory Provider + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Creation Time + + - **`directory_id`** + + `string` — Directory ID + + - **`expire_time`** + + `string`, format: `date-time` — Expiry Time + + - **`id`** + + `string` + + - **`last_used_time`** + + `string`, format: `date-time` — Last Used Time + + - **`secret_suffix`** + + `string` — Secret Suffix + + - **`status`** + + `string`, possible values: `"INACTIVE"` — Secret Status + + - **`stats`** + + `object` — Statistics and metrics related to the directory, such as synchronization status and error counts + + - **`group_updated_at`** + + `string`, format: `date-time` — Max time of Group Updated At for Directory + + - **`total_groups`** + + `integer`, format: `int32` — Total Groups in the Directory + + - **`total_users`** + + `integer`, format: `int32` — Total Users in the Directory + + - **`user_updated_at`** + + `string`, format: `date-time` — Max time of User Updated At for Directory + + - **`status`** + + `string` — Directory Status + + - **`total_groups`** + + `integer`, format: `int32` — Total number of groups in the directory + + - **`total_users`** + + `integer`, format: `int32` — Total number of users in the directory + +**Example:** + +```json +{ + "directory": { + "attribute_mappings": null, + "directory_endpoint": "https://yourapp.scalekit.com/api/v1/directoies/dir_123212312/scim/v2", + "directory_provider": "OKTA", + "directory_type": "SCIM", + "email": "john.doe@scalekit.cloud", + "enabled": true, + "groups_tracked": "ALL", + "id": "dir_121312434123312", + "last_synced_at": "2024-10-01T00:00:00Z", + "name": "Azure AD", + "organization_id": "org_121312434123312", + "role_assignments": null, + "secrets": [ + {} + ], + "stats": null, + "status": "IN_PROGRESS", + "total_groups": 10, + "total_users": 10 + } +} +``` + +### directoriesListDirectoriesResponse + +- **Type:**`object` + +* **`directories`** + + `array` — List of directories associated with the organization + + **Items:** + + - **`attribute_mappings`** + + `object` — Mappings between directory attributes and Scalekit user and group attributes + + - **`attributes`** + + `array` + + **Items:** + + - **`key`** + + `string` + + - **`map_to`** + + `string` + + - **`directory_endpoint`** + + `string` — The endpoint URL generated by Scalekit for synchronizing users and groups from the Directory Provider + + - **`directory_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "JUMPCLOUD", "PING_IDENTITY"` — Identity provider connected to this directory + + - **`directory_type`** + + `string`, possible values: `"SCIM", "LDAP", "POLL"` — Type of the directory, indicating the protocol or standard used for synchronization + + - **`email`** + + `string` — Email Id associated with Directory whose access will be used for polling + + - **`enabled`** + + `boolean` — Indicates whether the directory is currently enabled and actively synchronizing users and groups + + - **`groups_tracked`** + + `string` — It indicates if all groups are tracked or select groups are tracked + + - **`id`** + + `string` — Unique identifier of the directory + + - **`last_synced_at`** + + `string`, format: `date-time` — Timestamp of the last successful synchronization of users and groups from the Directory Provider + + - **`name`** + + `string` — Name of the directory, typically representing the connected Directory provider + + - **`organization_id`** + + `string` — Unique identifier of the organization to which the directory belongs + + - **`role_assignments`** + + `object` — Role assignments associated with the directory, defining group based role assignments + + - **`assignments`** + + `array` + + **Items:** + + - **`group_id`** + + `string` — group ID for the role mapping + + - **`role_name`** + + `string` + + - **`secrets`** + + `array` — List of secrets used for authenticating and synchronizing with the Directory Provider + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Creation Time + + - **`directory_id`** + + `string` — Directory ID + + - **`expire_time`** + + `string`, format: `date-time` — Expiry Time + + - **`id`** + + `string` + + - **`last_used_time`** + + `string`, format: `date-time` — Last Used Time + + - **`secret_suffix`** + + `string` — Secret Suffix + + - **`status`** + + `string`, possible values: `"INACTIVE"` — Secret Status + + - **`stats`** + + `object` — Statistics and metrics related to the directory, such as synchronization status and error counts + + - **`group_updated_at`** + + `string`, format: `date-time` — Max time of Group Updated At for Directory + + - **`total_groups`** + + `integer`, format: `int32` — Total Groups in the Directory + + - **`total_users`** + + `integer`, format: `int32` — Total Users in the Directory + + - **`user_updated_at`** + + `string`, format: `date-time` — Max time of User Updated At for Directory + + - **`status`** + + `string` — Directory Status + + - **`total_groups`** + + `integer`, format: `int32` — Total number of groups in the directory + + - **`total_users`** + + `integer`, format: `int32` — Total number of users in the directory + +**Example:** + +```json +{ + "directories": [ + { + "attribute_mappings": null, + "directory_endpoint": "https://yourapp.scalekit.com/api/v1/directoies/dir_123212312/scim/v2", + "directory_provider": "OKTA", + "directory_type": "SCIM", + "email": "john.doe@scalekit.cloud", + "enabled": true, + "groups_tracked": "ALL", + "id": "dir_121312434123312", + "last_synced_at": "2024-10-01T00:00:00Z", + "name": "Azure AD", + "organization_id": "org_121312434123312", + "role_assignments": null, + "secrets": [ + {} + ], + "stats": null, + "status": "IN_PROGRESS", + "total_groups": 10, + "total_users": 10 + } + ] +} +``` + +### directoriesListDirectoryGroupsResponse + +- **Type:**`object` + +* **`groups`** + + `array` — List of directory groups retrieved from the specified directory + + **Items:** + + - **`display_name`** + + `string` — Display Name + + - **`group_detail`** + + `object` — Complete Group Details Payload + + - **`id`** + + `string` — Group ID + + - **`total_users`** + + `integer`, format: `int32` — Total Users in the Group + + - **`updated_at`** + + `string`, format: `date-time` — Updated At + +* **`next_page_token`** + + `string` — Token to retrieve the next page of results. Use this token in the 'page\_token' field of the next request + +* **`prev_page_token`** + + `string` — Token to retrieve the previous page of results. Use this token in the 'page\_token' field of the next request + +* **`total_size`** + + `integer`, format: `int64` — Total number of groups matching the request criteria, regardless of pagination + +**Example:** + +```json +{ + "groups": [ + { + "display_name": "Admins", + "group_detail": {}, + "id": "dirgroup_121312434123312", + "total_users": 10, + "updated_at": "2024-10-01T00:00:00Z" + } + ], + "next_page_token": "", + "prev_page_token": "", + "total_size": 1 +} +``` + +### directoriesListDirectoryUsersResponse + +- **Type:**`object` + +* **`next_page_token`** + + `string` — Token for pagination. Use this token in the 'page\_token' field of the next request to fetch the subsequent page of users + +* **`prev_page_token`** + + `string` — Token for pagination. Use this token in the 'page\_token' field of the next request to fetch the prior page of users + +* **`total_size`** + + `integer`, format: `int64` — Total number of users available in the directory that match the request criteria + +* **`users`** + + `array` — List of directory users retrieved from the specified directory + + **Items:** + + - **`email`** + + `string` — Email + + - **`emails`** + + `array` — Emails + + **Items:** + + `string` + + - **`family_name`** + + `string` — Last Name + + - **`given_name`** + + `string` — First Name + + - **`groups`** + + `array` — Groups + + **Items:** + + - **`display_name`** + + `string` — Display Name + + - **`group_detail`** + + `object` — Complete Group Details Payload + + - **`id`** + + `string` — Group ID + + - **`total_users`** + + `integer`, format: `int32` — Total Users in the Group + + - **`updated_at`** + + `string`, format: `date-time` — Updated At + + - **`id`** + + `string` — User ID + + - **`preferred_username`** + + `string` — Preferred Username + + - **`updated_at`** + + `string`, format: `date-time` — Updated At + + - **`user_detail`** + + `object` — Complete User Details Payload + +**Example:** + +```json +{ + "next_page_token": "", + "prev_page_token": "", + "total_size": 1, + "users": [ + { + "email": "johndoe", + "emails": [ + "" + ], + "family_name": "Doe", + "given_name": "John", + "groups": [ + {} + ], + "id": "diruser_121312434123312", + "preferred_username": "johndoe", + "updated_at": "2024-10-01T00:00:00Z", + "user_detail": {} + } + ] +} +``` + +### directoriesRoleAssignment + +- **Type:**`object` + +* **`group_id`** + + `string` — group ID for the role mapping + +* **`role_name`** + + `string` + +**Example:** + +```json +{ + "group_id": "dirgroup_121312434123", + "role_name": "" +} +``` + +### directoriesRoleAssignments + +- **Type:**`object` + +* **`assignments`** + + `array` + + **Items:** + + - **`group_id`** + + `string` — group ID for the role mapping + + - **`role_name`** + + `string` + +**Example:** + +```json +{ + "assignments": [ + { + "group_id": "dirgroup_121312434123", + "role_name": "" + } + ] +} +``` + +### directoriesSecret + +- **Type:**`object` + +* **`create_time`** + + `string`, format: `date-time` — Creation Time + +* **`directory_id`** + + `string` — Directory ID + +* **`expire_time`** + + `string`, format: `date-time` — Expiry Time + +* **`id`** + + `string` + +* **`last_used_time`** + + `string`, format: `date-time` — Last Used Time + +* **`secret_suffix`** + + `string` — Secret Suffix + +* **`status`** + + `string`, possible values: `"INACTIVE"` — Secret Status + +**Example:** + +```json +{ + "create_time": "2024-10-01T00:00:00Z", + "directory_id": "dir_12362474900684814", + "expire_time": "2025-10-01T00:00:00Z", + "id": "", + "last_used_time": "2024-10-01T00:00:00Z", + "secret_suffix": "Nzg5", + "status": "INACTIVE" +} +``` + +### directoriesSecretStatus + +- **Type:**`string` + +**Example:** + +### directoriesStats + +- **Type:**`object` + +* **`group_updated_at`** + + `string`, format: `date-time` — Max time of Group Updated At for Directory + +* **`total_groups`** + + `integer`, format: `int32` — Total Groups in the Directory + +* **`total_users`** + + `integer`, format: `int32` — Total Users in the Directory + +* **`user_updated_at`** + + `string`, format: `date-time` — Max time of User Updated At for Directory + +**Example:** + +```json +{ + "group_updated_at": "2024-10-01T00:00:00Z", + "total_groups": 10, + "total_users": 10, + "user_updated_at": "2024-10-01T00:00:00Z" +} +``` + +### directoriesToggleDirectoryResponse + +- **Type:**`object` + +* **`enabled`** + + `boolean` — Specifies the directory's state after the toggle operation. A value of \`true\` indicates that the directory is enabled and actively synchronizing users and groups. A value of \`false\` means the directory is disabled, halting synchronization + +* **`error_message`** + + `string` — Contains a human-readable error message if the toggle operation encountered an issue. If the operation was successful, this field will be empty + +**Example:** + +```json +{ + "enabled": true, + "error_message": "The directory is already enabled" +} +``` + +### domainsCreateDomainResponse + +- **Type:**`object` + +* **`domain`** + + `object` — The newly created domain object with all configuration details and system-generated identifiers. + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the domain was first created. + + - **`domain`** + + `string` — The business domain name that was configured for allowed email domain functionality (e.g., company.com, subdomain.company.com). + + - **`domain_type`** + + `object` + + - **`environment_id`** + + `string` — The environment ID where this domain is configured. + + - **`id`** + + `string` — Scalekit-generated unique identifier for this domain record. + + - **`organization_id`** + + `string` — The organization to which the domain belongs. + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the domain was last updated. + + - **`verification_method`** + + `string`, possible values: `"ADMIN", "DNS", "NOT_APPLICABLE"` — Method that determines how domain ownership is verified. - ADMIN: domain is marked verified without DNS validation, typically by an admin. - DNS: domain must be verified by adding a TXT record to your DNS configuration. - NOT\_APPLICABLE: verification does not apply to this domain type. + + - **`verification_status`** + + `string`, possible values: `"PENDING", "VERIFIED", "FAILED", "AUTO_VERIFIED"` — Verification status of the domain. - PENDING: DNS TXT record has not been validated yet. - VERIFIED: domain confirmed via DNS TXT record validation or admin approval. - AUTO\_VERIFIED: domain verified automatically without DNS changes. - FAILED: DNS TXT record was not validated within the verification window. + +**Example:** + +```json +{ + "domain": { + "create_time": "2025-09-01T12:14:43.100000Z", + "domain": "customerdomain.com", + "domain_type": "ORGANIZATION_DOMAIN", + "environment_id": "env_58345499215790610", + "id": "dom_88351643129225005", + "organization_id": "org_81667076086825451", + "update_time": "2025-09-01T12:14:43.110455Z", + "verification_method": "ADMIN", + "verification_status": "AUTO_VERIFIED" + } +} +``` + +### domainsDomain + +- **Type:**`object` + +* **`create_time`** + + `string`, format: `date-time` — Timestamp when the domain was first created. + +* **`domain`** + + `string` — The business domain name that was configured for allowed email domain functionality (e.g., company.com, subdomain.company.com). + +* **`domain_type`** + + `object` + +* **`environment_id`** + + `string` — The environment ID where this domain is configured. + +* **`id`** + + `string` — Scalekit-generated unique identifier for this domain record. + +* **`organization_id`** + + `string` — The organization to which the domain belongs. + +* **`update_time`** + + `string`, format: `date-time` — Timestamp when the domain was last updated. + +* **`verification_method`** + + `string`, possible values: `"ADMIN", "DNS", "NOT_APPLICABLE"` — Method that determines how domain ownership is verified. - ADMIN: domain is marked verified without DNS validation, typically by an admin. - DNS: domain must be verified by adding a TXT record to your DNS configuration. - NOT\_APPLICABLE: verification does not apply to this domain type. + +* **`verification_status`** + + `string`, possible values: `"PENDING", "VERIFIED", "FAILED", "AUTO_VERIFIED"` — Verification status of the domain. - PENDING: DNS TXT record has not been validated yet. - VERIFIED: domain confirmed via DNS TXT record validation or admin approval. - AUTO\_VERIFIED: domain verified automatically without DNS changes. - FAILED: DNS TXT record was not validated within the verification window. + +**Example:** + +```json +{ + "create_time": "2025-09-01T12:14:43.100000Z", + "domain": "customerdomain.com", + "domain_type": "ORGANIZATION_DOMAIN", + "environment_id": "env_58345499215790610", + "id": "dom_88351643129225005", + "organization_id": "org_81667076086825451", + "update_time": "2025-09-01T12:14:43.110455Z", + "verification_method": "ADMIN", + "verification_status": "AUTO_VERIFIED" +} +``` + +### domainsDomainType + +- **Type:**`string` + +**Example:** + +### domainsGetDomainResponse + +- **Type:**`object` + +* **`domain`** + + `object` — The requested domain object with complete details including domain type, timestamps and configuration. + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the domain was first created. + + - **`domain`** + + `string` — The business domain name that was configured for allowed email domain functionality (e.g., company.com, subdomain.company.com). + + - **`domain_type`** + + `object` + + - **`environment_id`** + + `string` — The environment ID where this domain is configured. + + - **`id`** + + `string` — Scalekit-generated unique identifier for this domain record. + + - **`organization_id`** + + `string` — The organization to which the domain belongs. + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the domain was last updated. + + - **`verification_method`** + + `string`, possible values: `"ADMIN", "DNS", "NOT_APPLICABLE"` — Method that determines how domain ownership is verified. - ADMIN: domain is marked verified without DNS validation, typically by an admin. - DNS: domain must be verified by adding a TXT record to your DNS configuration. - NOT\_APPLICABLE: verification does not apply to this domain type. + + - **`verification_status`** + + `string`, possible values: `"PENDING", "VERIFIED", "FAILED", "AUTO_VERIFIED"` — Verification status of the domain. - PENDING: DNS TXT record has not been validated yet. - VERIFIED: domain confirmed via DNS TXT record validation or admin approval. - AUTO\_VERIFIED: domain verified automatically without DNS changes. - FAILED: DNS TXT record was not validated within the verification window. + +**Example:** + +```json +{ + "domain": { + "create_time": "2025-09-01T12:14:43.100000Z", + "domain": "customerdomain.com", + "domain_type": "ORGANIZATION_DOMAIN", + "environment_id": "env_58345499215790610", + "id": "dom_88351643129225005", + "organization_id": "org_81667076086825451", + "update_time": "2025-09-01T12:14:43.110455Z", + "verification_method": "ADMIN", + "verification_status": "AUTO_VERIFIED" + } +} +``` + +### domainsListDomainResponse + +- **Type:**`object` + +* **`domains`** + + `array` — Array of domain objects containing all domain details including verification status and configuration. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the domain was first created. + + - **`domain`** + + `string` — The business domain name that was configured for allowed email domain functionality (e.g., company.com, subdomain.company.com). + + - **`domain_type`** + + `object` + + - **`environment_id`** + + `string` — The environment ID where this domain is configured. + + - **`id`** + + `string` — Scalekit-generated unique identifier for this domain record. + + - **`organization_id`** + + `string` — The organization to which the domain belongs. + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the domain was last updated. + + - **`verification_method`** + + `string`, possible values: `"ADMIN", "DNS", "NOT_APPLICABLE"` — Method that determines how domain ownership is verified. - ADMIN: domain is marked verified without DNS validation, typically by an admin. - DNS: domain must be verified by adding a TXT record to your DNS configuration. - NOT\_APPLICABLE: verification does not apply to this domain type. + + - **`verification_status`** + + `string`, possible values: `"PENDING", "VERIFIED", "FAILED", "AUTO_VERIFIED"` — Verification status of the domain. - PENDING: DNS TXT record has not been validated yet. - VERIFIED: domain confirmed via DNS TXT record validation or admin approval. - AUTO\_VERIFIED: domain verified automatically without DNS changes. - FAILED: DNS TXT record was not validated within the verification window. + +* **`page_number`** + + `integer`, format: `int32` — Current page number in the pagination sequence. + +* **`page_size`** + + `integer`, format: `int32` — Number of domains returned in this page. + +**Example:** + +```json +{ + "domains": [ + { + "create_time": "2025-09-01T12:14:43.100000Z", + "domain": "customerdomain.com", + "domain_type": "ORGANIZATION_DOMAIN", + "environment_id": "env_58345499215790610", + "id": "dom_88351643129225005", + "organization_id": "org_81667076086825451", + "update_time": "2025-09-01T12:14:43.110455Z", + "verification_method": "ADMIN", + "verification_status": "AUTO_VERIFIED" + } + ], + "page_number": 1, + "page_size": 1 +} +``` + +### domainsVerificationMethod + +- **Type:**`string` + +**Example:** + +### domainsVerificationStatus + +- **Type:**`string` + +**Example:** + +### errdetailsDebugInfo + +- **Type:**`object` + +Describes additional debugging info. + +- **`detail`** + + `string` — Additional debugging information provided by the server. + +- **`stack_entries`** + + `array` — The stack trace entries indicating where the error occurred. + + **Items:** + + `string` + +**Example:** + +```json +{ + "detail": "", + "stack_entries": [ + "" + ] +} +``` + +### errdetailsErrorInfo + +- **Type:**`object` + +* **`debug_info`** + + `object` — Describes additional debugging info. + + - **`detail`** + + `string` — Additional debugging information provided by the server. + + - **`stack_entries`** + + `array` — The stack trace entries indicating where the error occurred. + + **Items:** + + `string` + +* **`error_code`** + + `string` + +* **`help_info`** + + `object` — HelpInfo provides documentation links attached to an error response. When present in ErrorInfo, clients should surface these links to help developers resolve the error. For example, a missing required field error may include a link to the relevant guide. + + - **`links`** + + `array` — One or more links relevant to resolving the error. + + **Items:** + + - **`description`** + + `string` — Human-readable label for the link (e.g. "User verification flow"). + + - **`url`** + + `string` — Absolute URL to the documentation page (e.g. "https\://docs.scalekit.com/..."). + +* **`localized_message_info`** + + `object` + + - **`locale`** + + `string` + + - **`message`** + + `string` + +* **`request_info`** + + `object` — Contains metadata about the request that clients can attach when filing a bug or providing other forms of feedback. + + - **`request_id`** + + `string` — An opaque string that should only be interpreted by the service generating it. For example, it can be used to identify requests in the service's logs. + + - **`serving_data`** + + `string` — Any data that was used to serve this request. For example, an encrypted stack trace that can be sent back to the service provider for debugging. + +* **`resource_info`** + + `object` — Describes the resource that is being accessed. + + - **`description`** + + `string` — Describes what error is encountered when accessing this resource. For example, updating a cloud project may require the \`writer\` permission on the developer console project. + + - **`owner`** + + `string` + + - **`required_permissions`** + + `array` — The required permissions needed to access the resource. + + **Items:** + + `string` + + - **`resource_name`** + + `string` + + - **`user`** + + `string` + +* **`tool_error_info`** + + `object` + + - **`execution_id`** + + `string` + + - **`tool_error_code`** + + `string` + + - **`tool_error_message`** + + `string` + +* **`validation_error_info`** + + `object` — Describes violations in a client request. This error type focuses on the syntactic aspects of the request. + + - **`field_violations`** + + `array` — Describes all violations in a client request. + + **Items:** + + - **`constraint`** + + `string` + + - **`description`** + + `string` — A description of why the request element is bad. + + - **`field`** + + `string` + +**Example:** + +```json +{ + "debug_info": { + "detail": "", + "stack_entries": [ + "" + ] + }, + "error_code": "", + "help_info": { + "links": [ + {} + ] + }, + "localized_message_info": { + "locale": "", + "message": "" + }, + "request_info": { + "request_id": "", + "serving_data": "" + }, + "resource_info": { + "description": "", + "owner": "", + "required_permissions": [ + "" + ], + "resource_name": "", + "user": "" + }, + "tool_error_info": { + "execution_id": "", + "tool_error_code": "", + "tool_error_message": "" + }, + "validation_error_info": { + "field_violations": [ + {} + ] + } +} +``` + +### errdetailsHelpInfo + +- **Type:**`object` + +HelpInfo provides documentation links attached to an error response. When present in ErrorInfo, clients should surface these links to help developers resolve the error. For example, a missing required field error may include a link to the relevant guide. + +- **`links`** + + `array` — One or more links relevant to resolving the error. + + **Items:** + + - **`description`** + + `string` — Human-readable label for the link (e.g. "User verification flow"). + + - **`url`** + + `string` — Absolute URL to the documentation page (e.g. "https\://docs.scalekit.com/..."). + +**Example:** + +```json +{ + "links": [ + { + "description": "", + "url": "" + } + ] +} +``` + +### errdetailsLocalizedMessageInfo + +- **Type:**`object` + +* **`locale`** + + `string` + +* **`message`** + + `string` + +**Example:** + +```json +{ + "locale": "", + "message": "" +} +``` + +### errdetailsRequestInfo + +- **Type:**`object` + +Contains metadata about the request that clients can attach when filing a bug or providing other forms of feedback. + +- **`request_id`** + + `string` — An opaque string that should only be interpreted by the service generating it. For example, it can be used to identify requests in the service's logs. + +- **`serving_data`** + + `string` — Any data that was used to serve this request. For example, an encrypted stack trace that can be sent back to the service provider for debugging. + +**Example:** + +```json +{ + "request_id": "", + "serving_data": "" +} +``` + +### errdetailsResourceInfo + +- **Type:**`object` + +Describes the resource that is being accessed. + +- **`description`** + + `string` — Describes what error is encountered when accessing this resource. For example, updating a cloud project may require the \`writer\` permission on the developer console project. + +- **`owner`** + + `string` + +- **`required_permissions`** + + `array` — The required permissions needed to access the resource. + + **Items:** + + `string` + +- **`resource_name`** + + `string` + +- **`user`** + + `string` + +**Example:** + +```json +{ + "description": "", + "owner": "", + "required_permissions": [ + "" + ], + "resource_name": "", + "user": "" +} +``` + +### errdetailsToolErrorInfo + +- **Type:**`object` + +* **`execution_id`** + + `string` + +* **`tool_error_code`** + + `string` + +* **`tool_error_message`** + + `string` + +**Example:** + +```json +{ + "execution_id": "", + "tool_error_code": "", + "tool_error_message": "" +} +``` + +### errdetailsValidationErrorInfo + +- **Type:**`object` + +Describes violations in a client request. This error type focuses on the syntactic aspects of the request. + +- **`field_violations`** + + `array` — Describes all violations in a client request. + + **Items:** + + - **`constraint`** + + `string` + + - **`description`** + + `string` — A description of why the request element is bad. + + - **`field`** + + `string` + +**Example:** + +```json +{ + "field_violations": [ + { + "constraint": "", + "description": "", + "field": "" + } + ] +} +``` + +### organizationsCreateOrganizationResponse + +- **Type:**`object` + +* **`organization`** + + `object` — The newly created organization containing its ID, settings, and metadata + + - **`create_time` (required)** + + `string`, format: `date-time` — Timestamp when the organization was created + + - **`display_name`** + + `string` — Name of the organization. Must be between 1 and 200 characters + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique scalekit-generated identifier that uniquely references an organization + + - **`metadata`** + + `object` — Key value pairs extension attributes. + + - **`region_code`** + + `string`, possible values: `"US", "EU"` — Geographic region code for the organization. Currently limited to US. + + - **`settings`** + + `object` — Configuration options that control organization-level features and capabilities + + - **`features`** + + `array` — List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization + + **Items:** + + - **`enabled` (required)** + + `boolean` — Whether the feature is enabled (true) or disabled (false) for this organization + + - **`name` (required)** + + `string` — Feature identifier. Supported values include: "sso" (Single Sign-On), "directory\_sync" (Directory Synchronization), "domain\_verification" (Domain Verification) + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the organization was last updated + +**Example:** + +```json +{ + "organization": { + "create_time": "2025-02-15T06:23:44.560000Z", + "display_name": "Megasoft", + "external_id": "my_unique_id", + "id": "org_59615193906282635", + "metadata": { + "additionalProperty": "" + }, + "region_code": "US", + "settings": null, + "update_time": "2025-02-15T06:23:44.560000Z" + } +} +``` + +### Feature represents the available features that can be enabled for an organization's portal link + +- **Type:**`string` + +* dir\_sync: Enables directory synchronization configuration in the portal +* sso: Enables Single Sign-On (SSO) configuration in the portal + +**Example:** + +### organizationsGeneratePortalLinkResponse + +- **Type:**`object` + +* **`link`** + + `object` — Contains the generated admin portal link details. The link URL can be shared with organization administrators to set up: Single Sign-On (SSO) authentication and directory synchronization + + - **`expire_time`** + + `string`, format: `date-time` — Expiry time of the link. The link is valid for 1 minute. + + - **`id`** + + `string` — Unique Identifier for the link + + - **`location`** + + `string` — Location of the link. This is the URL that can be used to access the Admin portal. The link is valid for 1 minute + +**Example:** + +```json +{ + "link": { + "expire_time": "2024-02-06T14:48:00Z", + "id": "lnk_123123123123123", + "location": "https://scalekit.com/portal/lnk_123123123123123" + } +} +``` + +### organizationsGetOrganizationResponse + +- **Type:**`object` + +* **`organization`** + + `object` — The newly created organization + + - **`create_time` (required)** + + `string`, format: `date-time` — Timestamp when the organization was created + + - **`display_name`** + + `string` — Name of the organization. Must be between 1 and 200 characters + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique scalekit-generated identifier that uniquely references an organization + + - **`metadata`** + + `object` — Key value pairs extension attributes. + + - **`region_code`** + + `string`, possible values: `"US", "EU"` — Geographic region code for the organization. Currently limited to US. + + - **`settings`** + + `object` — Configuration options that control organization-level features and capabilities + + - **`features`** + + `array` — List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization + + **Items:** + + - **`enabled` (required)** + + `boolean` — Whether the feature is enabled (true) or disabled (false) for this organization + + - **`name` (required)** + + `string` — Feature identifier. Supported values include: "sso" (Single Sign-On), "directory\_sync" (Directory Synchronization), "domain\_verification" (Domain Verification) + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the organization was last updated + +**Example:** + +```json +{ + "organization": { + "create_time": "2025-02-15T06:23:44.560000Z", + "display_name": "Megasoft", + "external_id": "my_unique_id", + "id": "org_59615193906282635", + "metadata": { + "additionalProperty": "" + }, + "region_code": "US", + "settings": null, + "update_time": "2025-02-15T06:23:44.560000Z" + } +} +``` + +### organizationsLink + +- **Type:**`object` + +* **`expire_time`** + + `string`, format: `date-time` — Expiry time of the link. The link is valid for 1 minute. + +* **`id`** + + `string` — Unique Identifier for the link + +* **`location`** + + `string` — Location of the link. This is the URL that can be used to access the Admin portal. The link is valid for 1 minute + +**Example:** + +```json +{ + "expire_time": "2024-02-06T14:48:00Z", + "id": "lnk_123123123123123", + "location": "https://scalekit.com/portal/lnk_123123123123123" +} +``` + +### organizationsListOrganizationsResponse + +- **Type:**`object` + +* **`next_page_token`** + + `string` — Pagination token for the next page of results. Use this token to fetch the next page. + +* **`organizations`** + + `array` — List of organization objects + + **Items:** + + - **`create_time` (required)** + + `string`, format: `date-time` — Timestamp when the organization was created + + - **`display_name`** + + `string` — Name of the organization. Must be between 1 and 200 characters + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique scalekit-generated identifier that uniquely references an organization + + - **`metadata`** + + `object` — Key value pairs extension attributes. + + - **`region_code`** + + `string`, possible values: `"US", "EU"` — Geographic region code for the organization. Currently limited to US. + + - **`settings`** + + `object` — Configuration options that control organization-level features and capabilities + + - **`features`** + + `array` — List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization + + **Items:** + + - **`enabled` (required)** + + `boolean` — Whether the feature is enabled (true) or disabled (false) for this organization + + - **`name` (required)** + + `string` — Feature identifier. Supported values include: "sso" (Single Sign-On), "directory\_sync" (Directory Synchronization), "domain\_verification" (Domain Verification) + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the organization was last updated + +* **`prev_page_token`** + + `string` — Pagination token for the previous page of results. Use this token to fetch the previous page. + +* **`total_size`** + + `integer`, format: `int64` — Total number of organizations in the environment. + +**Example:** + +```json +{ + "next_page_token": "", + "organizations": [ + { + "create_time": "2025-02-15T06:23:44.560000Z", + "display_name": "Megasoft", + "external_id": "my_unique_id", + "id": "org_59615193906282635", + "metadata": { + "additionalProperty": "" + }, + "region_code": "US", + "settings": null, + "update_time": "2025-02-15T06:23:44.560000Z" + } + ], + "prev_page_token": "", + "total_size": 30 +} +``` + +### organizationsOrganization + +- **Type:**`object` + +* **`create_time` (required)** + + `string`, format: `date-time` — Timestamp when the organization was created + +* **`display_name`** + + `string` — Name of the organization. Must be between 1 and 200 characters + +* **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + +* **`id`** + + `string` — Unique scalekit-generated identifier that uniquely references an organization + +* **`metadata`** + + `object` — Key value pairs extension attributes. + +* **`region_code`** + + `string`, possible values: `"US", "EU"` — Geographic region code for the organization. Currently limited to US. + +* **`settings`** + + `object` — Configuration options that control organization-level features and capabilities + + - **`features`** + + `array` — List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization + + **Items:** + + - **`enabled` (required)** + + `boolean` — Whether the feature is enabled (true) or disabled (false) for this organization + + - **`name` (required)** + + `string` — Feature identifier. Supported values include: "sso" (Single Sign-On), "directory\_sync" (Directory Synchronization), "domain\_verification" (Domain Verification) + +* **`update_time`** + + `string`, format: `date-time` — Timestamp when the organization was last updated + +**Example:** + +```json +{ + "create_time": "2025-02-15T06:23:44.560000Z", + "display_name": "Megasoft", + "external_id": "my_unique_id", + "id": "org_59615193906282635", + "metadata": { + "additionalProperty": "" + }, + "region_code": "US", + "settings": { + "features": [ + { + "enabled": true, + "name": "sso" + }, + { + "enabled": false, + "name": "directory_sync" + } + ] + }, + "update_time": "2025-02-15T06:23:44.560000Z" +} +``` + +### Organization Settings + +- **Type:**`object` + +Configuration options that control organization-level features and capabilities + +- **`features`** + + `array` — List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization + + **Items:** + + - **`enabled` (required)** + + `boolean` — Whether the feature is enabled (true) or disabled (false) for this organization + + - **`name` (required)** + + `string` — Feature identifier. Supported values include: "sso" (Single Sign-On), "directory\_sync" (Directory Synchronization), "domain\_verification" (Domain Verification) + +**Example:** + +```json +{ + "features": [ + { + "enabled": true, + "name": "sso" + }, + { + "enabled": false, + "name": "directory_sync" + } + ] +} +``` + +### Organization Feature Toggle + +- **Type:**`object` + +Controls the activation state of a specific organization feature + +- **`enabled` (required)** + + `boolean` — Whether the feature is enabled (true) or disabled (false) for this organization + +- **`name` (required)** + + `string` — Feature identifier. Supported values include: "sso" (Single Sign-On), "directory\_sync" (Directory Synchronization), "domain\_verification" (Domain Verification) + +**Example:** + +```json +{ + "enabled": true, + "name": "sso" +} +``` + +### organizationsOrganizationUserManagementSettings + +- **Type:**`object` + +* **`max_allowed_users`** + + `integer`, format: `int32` — Maximum number of users allowed in the organization. When nil (not set), there feature is not enabled. When explicitly set to zero, it also means no limit. When set to a positive integer, it enforces the maximum user limit. + +**Example:** + +```json +{ + "max_allowed_users": 100 +} +``` + +### organizationsUpdateOrganizationResponse + +- **Type:**`object` + +* **`organization`** + + `object` — Updated organization details + + - **`create_time` (required)** + + `string`, format: `date-time` — Timestamp when the organization was created + + - **`display_name`** + + `string` — Name of the organization. Must be between 1 and 200 characters + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique scalekit-generated identifier that uniquely references an organization + + - **`metadata`** + + `object` — Key value pairs extension attributes. + + - **`region_code`** + + `string`, possible values: `"US", "EU"` — Geographic region code for the organization. Currently limited to US. + + - **`settings`** + + `object` — Configuration options that control organization-level features and capabilities + + - **`features`** + + `array` — List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization + + **Items:** + + - **`enabled` (required)** + + `boolean` — Whether the feature is enabled (true) or disabled (false) for this organization + + - **`name` (required)** + + `string` — Feature identifier. Supported values include: "sso" (Single Sign-On), "directory\_sync" (Directory Synchronization), "domain\_verification" (Domain Verification) + + - **`update_time`** + + `string`, format: `date-time` — Timestamp when the organization was last updated + +**Example:** + +```json +{ + "organization": { + "create_time": "2025-02-15T06:23:44.560000Z", + "display_name": "Megasoft", + "external_id": "my_unique_id", + "id": "org_59615193906282635", + "metadata": { + "additionalProperty": "" + }, + "region_code": "US", + "settings": null, + "update_time": "2025-02-15T06:23:44.560000Z" + } +} +``` + +### organizationsUpsertUserManagementSettingsResponse + +- **Type:**`object` + +* **`settings`** + + `object` — The updated setting. + + - **`max_allowed_users`** + + `integer`, format: `int32` — Maximum number of users allowed in the organization. When nil (not set), there feature is not enabled. When explicitly set to zero, it also means no limit. When set to a positive integer, it enforces the maximum user limit. + +**Example:** + +```json +{ + "settings": { + "max_allowed_users": 100 + } +} +``` + +### passwordlessResendPasswordlessRequest + +- **Type:**`object` + +* **`auth_request_id`** + + `string` — The authentication request identifier from the original send passwordless email request. Use this to resend the Verification Code (OTP) or Magic Link to the same email address. + +**Example:** + +```json +{ + "auth_request_id": "h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ" +} +``` + +### passwordlessSendPasswordlessRequest + +- **Type:**`object` + +* **`email`** + + `string` — Email address where the passwordless authentication credentials will be sent. Must be a valid email format. + +* **`expires_in`** + + `integer`, format: `int64` — Time in seconds until the passwordless authentication expires. If not specified, defaults to 300 seconds (5 minutes) + +* **`magiclink_auth_uri`** + + `string` — Your application's callback URL where users will be redirected after clicking the magic link in their email. The link token will be appended as a query parameter as link\_token + +* **`state`** + + `string` — Custom state parameter that will be returned unchanged in the verification response. Use this to maintain application state between the authentication request and callback, such as the intended destination after login + +* **`template`** + + `string`, possible values: `"SIGNIN", "SIGNUP"` — Specifies the authentication intent for the passwordless request. Use SIGNIN for existing users or SIGNUP for new user registration. This affects the email template and user experience flow. + +* **`template_variables`** + + `object` — A set of key-value pairs to personalize the email template. \* You may include up to 30 key-value pairs. \* The following variable names are reserved by the system and cannot be supplied: \`otp\`, \`expiry\_time\_relative\`, \`link\`, \`expire\_time\`, \`expiry\_time\`. \* Every variable referenced in your email template must be included as a key-value pair. Use these variables to insert custom information, such as a team name, URL or the user's employee ID. All variables are interpolated before the email is sent, regardless of the email provider. + +**Example:** + +```json +{ + "email": "john.doe@example.com", + "expires_in": 300, + "magiclink_auth_uri": "https://yourapp.com/auth/passwordless/callback", + "state": "d62ivasry29lso", + "template": "SIGNIN", + "template_variables": { + "custom_variable_key": "custom_variable_value" + } +} +``` + +### passwordlessSendPasswordlessResponse + +- **Type:**`object` + +* **`auth_request_id`** + + `string` — Unique identifier for this passwordless authentication request. Use this ID to resend emails. + +* **`expires_at`** + + `string`, format: `int64` — Unix timestamp (seconds since epoch) when the passwordless authentication will expire. After this time, the OTP or magic link will no longer be valid. + +* **`expires_in`** + + `integer`, format: `int64` — Number of seconds from now until the passwordless authentication expires. This is a convenience field calculated from the expires\_at timestamp. + +* **`passwordless_type`** + + `string`, possible values: `"OTP", "LINK", "LINK_OTP"` — Type of passwordless authentication that was sent via email. OTP sends a numeric code, LINK sends a clickable magic link, and LINK\_OTP provides both options for user convenience. + +**Example:** + +```json +{ + "auth_request_id": "h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ", + "expires_at": 1748696575, + "expires_in": 300, + "passwordless_type": "OTP" +} +``` + +### passwordlessTemplateType + +- **Type:**`string` + +**Example:** + +### passwordlessVerifyPasswordLessRequest + +- **Type:**`object` + +* **`auth_request_id`** + + `string` — The authentication request identifier returned from the send passwordless email endpoint. Required when verifying OTP codes to link the verification with the original request. + +* **`code`** + + `string` — The Verification Code (OTP) received via email. This is typically a 6-digit numeric code that users enter manually to verify their identity. + +* **`link_token`** + + `string` — The unique token from the magic link URL received via email. Extract this token when users click the magic link and are redirected to your application to later verify the user. + +**Example:** + +```json +{ + "auth_request_id": "h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ", + "code": "123456", + "link_token": "afe9d61c-d80d-4020-a8ee-61765ab71cb3" +} +``` + +### passwordlessVerifyPasswordLessResponse + +- **Type:**`object` + +* **`email`** + + `string` — Email address of the successfully authenticated user. This confirms which email account was verified through the passwordless flow. + +* **`passwordless_type`** + + `string`, possible values: `"OTP", "LINK", "LINK_OTP"` — The type of passwordless authentication that was successfully verified, confirming which method the user completed. + +* **`state`** + + `string` — The custom state parameter that was provided in the original authentication request, returned unchanged. Use this to restore your application's context after authentication. + +* **`template`** + + `string`, possible values: `"SIGNIN", "SIGNUP"` — Specifies which email template to choose. For User Signin choose SIGNIN and for User Signup use SIGNUP + +**Example:** + +```json +{ + "email": "john.doe@example.com", + "passwordless_type": "OTP", + "state": "kdt7yiag28t341fr1", + "template": "SIGNIN" +} +``` + +### protobufNullValue + +- **Type:**`string` + +`NullValue` is a singleton enumeration to represent the null value for the `Value` type union. + +The JSON representation for `NullValue` is JSON `null`. + +**Example:** + +### rolesAddPermissionsToRoleResponse + +- **Type:**`object` + +* **`permissions`** + + `array` — List of all permissions belonging to the role after addition + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`is_scalekit_permission`** + + `boolean` — Indicates whether this permission is predefined by Scalekit + + - **`name`** + + `string` + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "permissions": [ + { + "create_time": "", + "description": "", + "id": "", + "is_scalekit_permission": true, + "name": "", + "update_time": "" + } + ] +} +``` + +### rolesCreateOrganizationRoleResponse + +- **Type:**`object` + +* **`role`** + + `object` + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "role": { + "default_creator": true, + "default_member": true, + "dependent_roles_count": 3, + "description": "Can create, edit, and publish content but cannot delete or manage users", + "display_name": "Content Editor", + "extends": "admin_role", + "id": "role_1234abcd5678efgh", + "is_org_role": true, + "name": "content_editor", + "permissions": [ + { + "description": "Read Content", + "name": "read:content", + "role_name": "admin_role" + }, + { + "description": "Write Content", + "name": "write:content", + "role_name": "editor_role" + } + ] + } +} +``` + +### rolesCreatePermissionResponse + +- **Type:**`object` + +* **`permission`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`is_scalekit_permission`** + + `boolean` — Indicates whether this permission is predefined by Scalekit + + - **`name`** + + `string` + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "permission": { + "create_time": "", + "description": "", + "id": "", + "is_scalekit_permission": true, + "name": "", + "update_time": "" + } +} +``` + +### rolesCreateRoleResponse + +- **Type:**`object` + +* **`role`** + + `object` — The created role object with system-generated ID and all configuration details. + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "role": { + "description": "Can edit content", + "display_name": "Content Editor", + "id": "role_1234abcd5678efgh", + "name": "content_editor" + } +} +``` + +### rolesGetOrganizationRoleResponse + +- **Type:**`object` + +* **`role`** + + `object` + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "role": { + "default_creator": true, + "default_member": true, + "dependent_roles_count": 3, + "description": "Can create, edit, and publish content but cannot delete or manage users", + "display_name": "Content Editor", + "extends": "admin_role", + "id": "role_1234abcd5678efgh", + "is_org_role": true, + "name": "content_editor", + "permissions": [ + { + "description": "Read Content", + "name": "read:content", + "role_name": "admin_role" + }, + { + "description": "Write Content", + "name": "write:content", + "role_name": "editor_role" + } + ] + } +} +``` + +### rolesGetPermissionResponse + +- **Type:**`object` + +* **`permission`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`is_scalekit_permission`** + + `boolean` — Indicates whether this permission is predefined by Scalekit + + - **`name`** + + `string` + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "permission": { + "create_time": "", + "description": "", + "id": "", + "is_scalekit_permission": true, + "name": "", + "update_time": "" + } +} +``` + +### rolesGetRoleResponse + +- **Type:**`object` + +* **`role`** + + `object` — The complete role object with all metadata, permissions, and inheritance details. + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "role": { + "dependent_roles_count": 2, + "display_name": "Content Editor", + "id": "role_1234abcd5678efgh", + "name": "content_editor", + "permissions": [ + { + "name": "read:content" + } + ] + } +} +``` + +### rolesGetRoleUsersCountResponse + +- **Type:**`object` + +* **`count`** + + `string`, format: `int64` — Number of users associated with the role + +**Example:** + +```json +{ + "count": 10 +} +``` + +### rolesListDependentRolesResponse + +- **Type:**`object` + +* **`roles`** + + `array` — List of dependent roles + + **Items:** + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "roles": [ + { + "default_creator": true, + "default_member": true, + "dependent_roles_count": 3, + "description": "Can create, edit, and publish content but cannot delete or manage users", + "display_name": "Content Editor", + "extends": "admin_role", + "id": "role_1234abcd5678efgh", + "is_org_role": true, + "name": "content_editor", + "permissions": [ + { + "description": "Read Content", + "name": "read:content", + "role_name": "admin_role" + }, + { + "description": "Write Content", + "name": "write:content", + "role_name": "editor_role" + } + ] + } + ] +} +``` + +### rolesListEffectiveRolePermissionsResponse + +- **Type:**`object` + +* **`permissions`** + + `array` — List of all effective permissions including those inherited from base roles + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`is_scalekit_permission`** + + `boolean` — Indicates whether this permission is predefined by Scalekit + + - **`name`** + + `string` + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "permissions": [ + { + "create_time": "", + "description": "", + "id": "", + "is_scalekit_permission": true, + "name": "", + "update_time": "" + } + ] +} +``` + +### rolesListOrganizationRolesResponse + +- **Type:**`object` + +* **`roles`** + + `array` — List of roles objects + + **Items:** + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "roles": [ + { + "default_creator": true, + "default_member": true, + "dependent_roles_count": 3, + "description": "Can create, edit, and publish content but cannot delete or manage users", + "display_name": "Content Editor", + "extends": "admin_role", + "id": "role_1234abcd5678efgh", + "is_org_role": true, + "name": "content_editor", + "permissions": [ + { + "description": "Read Content", + "name": "read:content", + "role_name": "admin_role" + }, + { + "description": "Write Content", + "name": "write:content", + "role_name": "editor_role" + } + ] + } + ] +} +``` + +### rolesListPermissionsResponse + +- **Type:**`object` + +* **`next_page_token`** + + `string` — Token to retrieve next page of results + +* **`permissions`** + + `array` + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`is_scalekit_permission`** + + `boolean` — Indicates whether this permission is predefined by Scalekit + + - **`name`** + + `string` + + - **`update_time`** + + `string`, format: `date-time` + +* **`prev_page_token`** + + `string` — Token to retrieve previous page of results + +* **`total_size`** + + `integer`, format: `int64` — Total number of permissions available + +**Example:** + +```json +{ + "next_page_token": "token_def456", + "permissions": [ + { + "create_time": "", + "description": "", + "id": "", + "is_scalekit_permission": true, + "name": "", + "update_time": "" + } + ], + "prev_page_token": "token_def456", + "total_size": 150 +} +``` + +### rolesListRolePermissionsResponse + +- **Type:**`object` + +* **`permissions`** + + `array` — List of permissions directly assigned to the role + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`is_scalekit_permission`** + + `boolean` — Indicates whether this permission is predefined by Scalekit + + - **`name`** + + `string` + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "permissions": [ + { + "create_time": "", + "description": "", + "id": "", + "is_scalekit_permission": true, + "name": "", + "update_time": "" + } + ] +} +``` + +### rolesListRolesResponse + +- **Type:**`object` + +* **`roles`** + + `array` — List of all roles in the environment with their metadata and optionally their permissions. + + **Items:** + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "roles": [ + { + "display_name": "Administrator", + "id": "role_1234abcd5678efgh", + "name": "admin" + }, + { + "display_name": "Viewer", + "id": "role_9876zyxw5432vuts", + "name": "viewer" + } + ] +} +``` + +### Permission Entity + +- **Type:**`object` + +* **`create_time`** + + `string`, format: `date-time` + +* **`description`** + + `string` + +* **`id`** + + `string` + +* **`is_scalekit_permission`** + + `boolean` — Indicates whether this permission is predefined by Scalekit + +* **`name`** + + `string` + +* **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "create_time": "", + "description": "", + "id": "", + "is_scalekit_permission": true, + "name": "", + "update_time": "" +} +``` + +### rolesPermissionType + +- **Type:**`string` + +**Example:** + +### RolePermissions represents a permission with role source information + +- **Type:**`object` + +* **`create_time`** + + `string`, format: `date-time` + +* **`description`** + + `string` + +* **`id`** + + `string` + +* **`name`** + + `string` + +* **`role_name`** + + `string` — Name of the role from which this permission was sourced + +* **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "create_time": "", + "description": "", + "id": "", + "name": "", + "role_name": "admin_role", + "update_time": "" +} +``` + +### rolesUpdateDefaultOrganizationRolesResponse + +- **Type:**`object` + +* **`default_member`** + + `object` — Updated default member role + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "default_member": { + "description": "Role for regular members", + "display_name": "Member Role", + "id": "role_0987654321", + "name": "member" + } +} +``` + +### rolesUpdateDefaultRole + +- **Type:**`object` + +* **`id`** + + `string` + +* **`name`** + + `string` — Unique name of the role + +**Example:** + +```json +{ + "id": "", + "name": "creator" +} +``` + +### rolesUpdateDefaultRolesRequest + +- **Type:**`object` + +* **`default_creator`** + + `object` — Default creator role (deprecated - use default\_creator\_role field instead) + + - **`id`** + + `string` + + - **`name`** + + `string` — Unique name of the role + +* **`default_creator_role`** + + `string` — Name of the role to set as the default creator role. This role will be automatically assigned to users who create new resources in the environment. Must be a valid role name that exists in the environment. + +* **`default_member`** + + `object` — Default member role (deprecated - use default\_member\_role field instead) + + - **`id`** + + `string` + + - **`name`** + + `string` — Unique name of the role + +* **`default_member_role`** + + `string` — Name of the role to set as the default member role. This role will be automatically assigned to new users when they join the environment. Must be a valid role name that exists in the environment. + +**Example:** + +```json +{ + "default_creator": { + "description": "Role for creating resources", + "display_name": "Creator Role", + "id": "role_1234567890", + "name": "creator" + }, + "default_creator_role": "creator", + "default_member": { + "description": "Role for regular members", + "display_name": "Member Role", + "id": "role_0987654321", + "name": "member" + }, + "default_member_role": "member" +} +``` + +### rolesUpdateDefaultRolesResponse + +- **Type:**`object` + +* **`default_creator`** + + `object` — The role that is now set as the default creator role for the environment. Contains complete role information including permissions and metadata. + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +* **`default_member`** + + `object` — The role that is now set as the default member role for the environment. Contains complete role information including permissions and metadata. + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "default_creator": { + "description": "Role for creating resources", + "display_name": "Creator Role", + "id": "role_1234567890", + "name": "creator" + }, + "default_member": { + "description": "Role for regular members", + "display_name": "Member Role", + "id": "role_0987654321", + "name": "member" + } +} +``` + +### rolesUpdateOrganizationRoleResponse + +- **Type:**`object` + +* **`role`** + + `object` + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "role": { + "default_creator": true, + "default_member": true, + "dependent_roles_count": 3, + "description": "Can create, edit, and publish content but cannot delete or manage users", + "display_name": "Content Editor", + "extends": "admin_role", + "id": "role_1234abcd5678efgh", + "is_org_role": true, + "name": "content_editor", + "permissions": [ + { + "description": "Read Content", + "name": "read:content", + "role_name": "admin_role" + }, + { + "description": "Write Content", + "name": "write:content", + "role_name": "editor_role" + } + ] + } +} +``` + +### rolesUpdatePermissionResponse + +- **Type:**`object` + +* **`permission`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`is_scalekit_permission`** + + `boolean` — Indicates whether this permission is predefined by Scalekit + + - **`name`** + + `string` + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "permission": { + "create_time": "", + "description": "", + "id": "", + "is_scalekit_permission": true, + "name": "", + "update_time": "" + } +} +``` + +### rolesUpdateRoleResponse + +- **Type:**`object` + +* **`role`** + + `object` — The updated role object with all current configuration details. + + - **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + + - **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + + - **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + + - **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + + - **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + + - **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + + - **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + + - **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + + - **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + + - **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "role": { + "description": "Can edit and approve content", + "display_name": "Senior Editor", + "id": "role_1234abcd5678efgh", + "name": "content_editor" + } +} +``` + +### sessionsAuthenticatedClients + +- **Type:**`object` + +AuthenticatedClients represents an authenticated client in a session along with its organization context. + +- **`client_id`** + + `string` — Unique identifier of the authenticated client application. + +- **`organization_id`** + + `string` — Active or last active Organization ID associated with the authenticated client. + +**Example:** + +```json +{ + "client_id": "skc_1234567890", + "organization_id": "org_1234567890" +} +``` + +### sessionsDeviceDetails + +- **Type:**`object` + +* **`browser`** + + `string` — Browser name and family extracted from the user agent. Examples: Chrome, Safari, Firefox, Edge, Mobile Safari. + +* **`browser_version`** + + `string` — Version of the browser application. Represents the specific release version of the browser being used. + +* **`device_type`** + + `string` — Categorized device type classification. Possible values: 'desktop' (traditional computers), 'mobile' (smartphones and small tablets), 'tablet' (large tablets), 'other'. Useful for displaying session information by device category. + +* **`ip`** + + `string` — IP address of the device that initiated the session. This is the public-facing IP address used to connect to the application. Useful for security audits and geographic distribution analysis. + +* **`location`** + + `object` — Geographic location information derived from IP address geolocation. Includes country, region, city, and coordinates. Note: Based on IP location data and may not represent the user's exact physical location. + + - **`city`** + + `string` — City name where the session originated based on IP geolocation. Approximate location derived from IP address. + + - **`latitude`** + + `string` — Latitude coordinate of the estimated location. Decimal format (e.g., '37.7749'). Note: Represents IP geolocation center and may not be precise. + + - **`longitude`** + + `string` — Longitude coordinate of the estimated location. Decimal format (e.g., '-122.4194'). Note: Represents IP geolocation center and may not be precise. + + - **`region`** + + `string` — Geographic region name derived from IP geolocation. Represents the country-level location (e.g., 'United States', 'France'). + + - **`region_subdivision`** + + `string` — Regional subdivision code or name (e.g., state abbreviation for US, province for Canada). Two-letter ISO format when applicable. + +* **`os`** + + `string` — Operating system name extracted from the user agent and device headers. Examples: macOS, Windows, Linux, iOS, Android. + +* **`os_version`** + + `string` — Version of the operating system. Represents the specific OS release the device is running. + +* **`user_agent`** + + `string` — Complete HTTP User-Agent header string from the client request. Contains browser type, version, and operating system information. Used for detailed device fingerprinting and user agent analysis. + +**Example:** + +```json +{ + "browser": "Chrome", + "browser_version": "120.0.0.0", + "device_type": "desktop", + "ip": "192.0.2.1", + "location": { + "city": "San Francisco", + "latitude": "37.7749", + "longitude": "-122.4194", + "region": "United States", + "region_subdivision": "CA" + }, + "os": "macOS", + "os_version": "14.2", + "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" +} +``` + +### sessionsRevokeAllUserSessionsResponse + +- **Type:**`object` + +* **`revoked_sessions`** + + `array` — List of all sessions that were revoked, including detailed information for each revoked session with IDs, timestamps, and device details. + + **Items:** + + - **`absolute_expires_at`** + + `string`, format: `date-time` — The absolute expiration timestamp that was configured for this session before revocation. Represents the hard deadline regardless of activity. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was originally created before revocation. + + - **`expired_at`** + + `string`, format: `date-time` — Timestamp when the session was actually terminated. Set to the revocation time when the session is revoked. + + - **`idle_expires_at`** + + `string`, format: `date-time` — The idle expiration timestamp that was configured for this session before revocation. Represents when the session would have expired due to inactivity. + + - **`last_active_at`** + + `string`, format: `date-time` — Timestamp of the last recorded user activity in this session before revocation. Helps identify inactive sessions that were revoked. + + - **`logout_at`** + + `string`, format: `date-time` — Timestamp when the user explicitly logged out (if applicable). Null if the session was revoked without prior logout. + + - **`session_id`** + + `string` — Unique identifier for the revoked session. System-generated read-only field. + + - **`status`** + + `string` — Status of the session after revocation. Always 'revoked' since only active sessions can be revoked. Sessions that were already expired or logged out are not included in the revocation response. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was last modified before revocation. + + - **`user_id`** + + `string` — Unique identifier for the user who owned this session. + +* **`total_revoked`** + + `integer`, format: `int64` — Total count of active sessions that were revoked. Useful for confirmation and audit logging. + +**Example:** + +```json +{ + "revoked_sessions": [ + { + "absolute_expires_at": "2025-01-22T10:30:00Z", + "created_at": "2025-01-15T10:30:00Z", + "expired_at": "2025-01-15T12:00:00Z", + "idle_expires_at": "2025-01-15T11:30:00Z", + "last_active_at": "2025-01-15T10:55:30Z", + "logout_at": "2025-01-15T14:00:00Z", + "session_id": "ses_1234567890123456", + "status": "revoked", + "updated_at": "2025-01-15T10:45:00Z", + "user_id": "usr_1234567890123456" + } + ], + "total_revoked": 5 +} +``` + +### sessionsRevokeSessionResponse + +- **Type:**`object` + +* **`revoked_session`** + + `object` — Details of the revoked session including session ID, user ID, creation and revocation timestamps, and final device information. + + - **`absolute_expires_at`** + + `string`, format: `date-time` — The absolute expiration timestamp that was configured for this session before revocation. Represents the hard deadline regardless of activity. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was originally created before revocation. + + - **`expired_at`** + + `string`, format: `date-time` — Timestamp when the session was actually terminated. Set to the revocation time when the session is revoked. + + - **`idle_expires_at`** + + `string`, format: `date-time` — The idle expiration timestamp that was configured for this session before revocation. Represents when the session would have expired due to inactivity. + + - **`last_active_at`** + + `string`, format: `date-time` — Timestamp of the last recorded user activity in this session before revocation. Helps identify inactive sessions that were revoked. + + - **`logout_at`** + + `string`, format: `date-time` — Timestamp when the user explicitly logged out (if applicable). Null if the session was revoked without prior logout. + + - **`session_id`** + + `string` — Unique identifier for the revoked session. System-generated read-only field. + + - **`status`** + + `string` — Status of the session after revocation. Always 'revoked' since only active sessions can be revoked. Sessions that were already expired or logged out are not included in the revocation response. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was last modified before revocation. + + - **`user_id`** + + `string` — Unique identifier for the user who owned this session. + +**Example:** + +```json +{ + "revoked_session": { + "absolute_expires_at": "2025-01-22T10:30:00Z", + "created_at": "2025-01-15T10:30:00Z", + "expired_at": "2025-01-15T12:00:00Z", + "idle_expires_at": "2025-01-15T11:30:00Z", + "last_active_at": "2025-01-15T10:55:30Z", + "logout_at": "2025-01-15T14:00:00Z", + "session_id": "ses_1234567890123456", + "status": "revoked", + "updated_at": "2025-01-15T10:45:00Z", + "user_id": "usr_1234567890123456" + } +} +``` + +### sessionsRevokedSessionDetails + +- **Type:**`object` + +* **`absolute_expires_at`** + + `string`, format: `date-time` — The absolute expiration timestamp that was configured for this session before revocation. Represents the hard deadline regardless of activity. + +* **`created_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was originally created before revocation. + +* **`expired_at`** + + `string`, format: `date-time` — Timestamp when the session was actually terminated. Set to the revocation time when the session is revoked. + +* **`idle_expires_at`** + + `string`, format: `date-time` — The idle expiration timestamp that was configured for this session before revocation. Represents when the session would have expired due to inactivity. + +* **`last_active_at`** + + `string`, format: `date-time` — Timestamp of the last recorded user activity in this session before revocation. Helps identify inactive sessions that were revoked. + +* **`logout_at`** + + `string`, format: `date-time` — Timestamp when the user explicitly logged out (if applicable). Null if the session was revoked without prior logout. + +* **`session_id`** + + `string` — Unique identifier for the revoked session. System-generated read-only field. + +* **`status`** + + `string` — Status of the session after revocation. Always 'revoked' since only active sessions can be revoked. Sessions that were already expired or logged out are not included in the revocation response. + +* **`updated_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was last modified before revocation. + +* **`user_id`** + + `string` — Unique identifier for the user who owned this session. + +**Example:** + +```json +{ + "absolute_expires_at": "2025-01-22T10:30:00Z", + "created_at": "2025-01-15T10:30:00Z", + "expired_at": "2025-01-15T12:00:00Z", + "idle_expires_at": "2025-01-15T11:30:00Z", + "last_active_at": "2025-01-15T10:55:30Z", + "logout_at": "2025-01-15T14:00:00Z", + "session_id": "ses_1234567890123456", + "status": "revoked", + "updated_at": "2025-01-15T10:45:00Z", + "user_id": "usr_1234567890123456" +} +``` + +### sessionsSessionDetails + +- **Type:**`object` + +* **`absolute_expires_at`** + + `string`, format: `date-time` — Hard expiration timestamp for the session regardless of user activity. The session will be forcibly terminated at this time. This represents the maximum session lifetime from creation. + +* **`authenticated_clients`** + + `array` — Details of the authenticated clients for this session: client ID and organization context. + + **Items:** + + - **`client_id`** + + `string` — Unique identifier of the authenticated client application. + + - **`organization_id`** + + `string` — Active or last active Organization ID associated with the authenticated client. + +* **`authenticated_organizations`** + + `array` — List of organization IDs that have been authenticated for this user within the current session. Contains all organizations where the user has successfully completed SSO or authentication. + + **Items:** + + `string` + +* **`created_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was created. This is set once at session creation and remains constant throughout the session lifetime. + +* **`device`** + + `object` — Complete device metadata associated with this session including browser, operating system, device type, and geographic location based on IP address. + + - **`browser`** + + `string` — Browser name and family extracted from the user agent. Examples: Chrome, Safari, Firefox, Edge, Mobile Safari. + + - **`browser_version`** + + `string` — Version of the browser application. Represents the specific release version of the browser being used. + + - **`device_type`** + + `string` — Categorized device type classification. Possible values: 'desktop' (traditional computers), 'mobile' (smartphones and small tablets), 'tablet' (large tablets), 'other'. Useful for displaying session information by device category. + + - **`ip`** + + `string` — IP address of the device that initiated the session. This is the public-facing IP address used to connect to the application. Useful for security audits and geographic distribution analysis. + + - **`location`** + + `object` — Geographic location information derived from IP address geolocation. Includes country, region, city, and coordinates. Note: Based on IP location data and may not represent the user's exact physical location. + + - **`city`** + + `string` — City name where the session originated based on IP geolocation. Approximate location derived from IP address. + + - **`latitude`** + + `string` — Latitude coordinate of the estimated location. Decimal format (e.g., '37.7749'). Note: Represents IP geolocation center and may not be precise. + + - **`longitude`** + + `string` — Longitude coordinate of the estimated location. Decimal format (e.g., '-122.4194'). Note: Represents IP geolocation center and may not be precise. + + - **`region`** + + `string` — Geographic region name derived from IP geolocation. Represents the country-level location (e.g., 'United States', 'France'). + + - **`region_subdivision`** + + `string` — Regional subdivision code or name (e.g., state abbreviation for US, province for Canada). Two-letter ISO format when applicable. + + - **`os`** + + `string` — Operating system name extracted from the user agent and device headers. Examples: macOS, Windows, Linux, iOS, Android. + + - **`os_version`** + + `string` — Version of the operating system. Represents the specific OS release the device is running. + + - **`user_agent`** + + `string` — Complete HTTP User-Agent header string from the client request. Contains browser type, version, and operating system information. Used for detailed device fingerprinting and user agent analysis. + +* **`expired_at`** + + `string`, format: `date-time` — Timestamp when the session was terminated. Null if the session is still active. Set when the session expires due to reaching idle\_expires\_at or absolute\_expires\_at timeout, or when administratively revoked. Not set for user-initiated logout (see logout\_at instead). + +* **`idle_expires_at`** + + `string`, format: `date-time` — Projected expiration timestamp if the session remains idle without user activity. This timestamp is recalculated with each user activity. Session will be automatically terminated at this time if no activity occurs. + +* **`last_active_at`** + + `string`, format: `date-time` — Timestamp of the most recent user activity detected in this session. Updated on each API request or user interaction. Used to determine if a session has exceeded the idle timeout threshold. + +* **`logout_at`** + + `string`, format: `date-time` — Timestamp when the user explicitly logged out from the session. Null if the user has not logged out. When set, indicates the session ended due to explicit user logout rather than timeout. + +* **`organization_id`** + + `string` — Organization ID for the user's most recently active organization within this session. This represents the primary organization context for the current session. + +* **`session_id`** + + `string` — Unique identifier for the session. System-generated read-only field used to reference this session. + +* **`status`** + + `string` — Current operational status of the session. Possible values: 'active' (session is valid and requests are allowed), 'expired' (session terminated due to idle or absolute timeout), 'revoked' (session was administratively revoked), 'logout' (user explicitly logged out). Use this to determine if the session can be used for new requests. + +* **`updated_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was last updated. Updated whenever session state changes such as organization context changes or metadata updates. + +* **`user_id`** + + `string` — Unique identifier for the user who owns and is authenticated within this session. + +**Example:** + +```json +{ + "absolute_expires_at": "2025-01-22T10:30:00Z", + "authenticated_clients": [ + { + "client_id": "skc_1234567890", + "organization_id": "org_1234567890" + } + ], + "authenticated_organizations": [ + "org_123", + "org_456" + ], + "created_at": "2025-01-15T10:30:00Z", + "device": { + "browser": "Chrome", + "browser_version": "120.0.0.0", + "device_type": "desktop", + "ip": "192.0.2.1", + "location": null, + "os": "macOS", + "os_version": "14.2", + "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" + }, + "expired_at": "2025-01-15T12:00:00Z", + "idle_expires_at": "2025-01-15T11:30:00Z", + "last_active_at": "2025-01-15T10:55:30Z", + "logout_at": "2025-01-15T14:00:00Z", + "organization_id": "org_1234567890123456", + "session_id": "ses_1234567890123456", + "status": "active", + "updated_at": "2025-01-15T10:45:00Z", + "user_id": "usr_1234567890123456" +} +``` + +### sessionsUserSessionDetails + +- **Type:**`object` + +* **`next_page_token`** + + `string` — Pagination token for retrieving the next page of results. Empty string if there are no more pages (you have reached the final page of results). + +* **`prev_page_token`** + + `string` — Pagination token for retrieving the previous page of results. Empty string for the first page. Use this to navigate backward through result pages. + +* **`sessions`** + + `array` — Array of session objects for the requested user. May contain fewer entries than the requested page\_size when reaching the final page of results. + + **Items:** + + - **`absolute_expires_at`** + + `string`, format: `date-time` — Hard expiration timestamp for the session regardless of user activity. The session will be forcibly terminated at this time. This represents the maximum session lifetime from creation. + + - **`authenticated_clients`** + + `array` — Details of the authenticated clients for this session: client ID and organization context. + + **Items:** + + - **`client_id`** + + `string` — Unique identifier of the authenticated client application. + + - **`organization_id`** + + `string` — Active or last active Organization ID associated with the authenticated client. + + - **`authenticated_organizations`** + + `array` — List of organization IDs that have been authenticated for this user within the current session. Contains all organizations where the user has successfully completed SSO or authentication. + + **Items:** + + `string` + + - **`created_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was created. This is set once at session creation and remains constant throughout the session lifetime. + + - **`device`** + + `object` — Complete device metadata associated with this session including browser, operating system, device type, and geographic location based on IP address. + + - **`browser`** + + `string` — Browser name and family extracted from the user agent. Examples: Chrome, Safari, Firefox, Edge, Mobile Safari. + + - **`browser_version`** + + `string` — Version of the browser application. Represents the specific release version of the browser being used. + + - **`device_type`** + + `string` — Categorized device type classification. Possible values: 'desktop' (traditional computers), 'mobile' (smartphones and small tablets), 'tablet' (large tablets), 'other'. Useful for displaying session information by device category. + + - **`ip`** + + `string` — IP address of the device that initiated the session. This is the public-facing IP address used to connect to the application. Useful for security audits and geographic distribution analysis. + + - **`location`** + + `object` — Geographic location information derived from IP address geolocation. Includes country, region, city, and coordinates. Note: Based on IP location data and may not represent the user's exact physical location. + + - **`city`** + + `string` — City name where the session originated based on IP geolocation. Approximate location derived from IP address. + + - **`latitude`** + + `string` — Latitude coordinate of the estimated location. Decimal format (e.g., '37.7749'). Note: Represents IP geolocation center and may not be precise. + + - **`longitude`** + + `string` — Longitude coordinate of the estimated location. Decimal format (e.g., '-122.4194'). Note: Represents IP geolocation center and may not be precise. + + - **`region`** + + `string` — Geographic region name derived from IP geolocation. Represents the country-level location (e.g., 'United States', 'France'). + + - **`region_subdivision`** + + `string` — Regional subdivision code or name (e.g., state abbreviation for US, province for Canada). Two-letter ISO format when applicable. + + - **`os`** + + `string` — Operating system name extracted from the user agent and device headers. Examples: macOS, Windows, Linux, iOS, Android. + + - **`os_version`** + + `string` — Version of the operating system. Represents the specific OS release the device is running. + + - **`user_agent`** + + `string` — Complete HTTP User-Agent header string from the client request. Contains browser type, version, and operating system information. Used for detailed device fingerprinting and user agent analysis. + + - **`expired_at`** + + `string`, format: `date-time` — Timestamp when the session was terminated. Null if the session is still active. Set when the session expires due to reaching idle\_expires\_at or absolute\_expires\_at timeout, or when administratively revoked. Not set for user-initiated logout (see logout\_at instead). + + - **`idle_expires_at`** + + `string`, format: `date-time` — Projected expiration timestamp if the session remains idle without user activity. This timestamp is recalculated with each user activity. Session will be automatically terminated at this time if no activity occurs. + + - **`last_active_at`** + + `string`, format: `date-time` — Timestamp of the most recent user activity detected in this session. Updated on each API request or user interaction. Used to determine if a session has exceeded the idle timeout threshold. + + - **`logout_at`** + + `string`, format: `date-time` — Timestamp when the user explicitly logged out from the session. Null if the user has not logged out. When set, indicates the session ended due to explicit user logout rather than timeout. + + - **`organization_id`** + + `string` — Organization ID for the user's most recently active organization within this session. This represents the primary organization context for the current session. + + - **`session_id`** + + `string` — Unique identifier for the session. System-generated read-only field used to reference this session. + + - **`status`** + + `string` — Current operational status of the session. Possible values: 'active' (session is valid and requests are allowed), 'expired' (session terminated due to idle or absolute timeout), 'revoked' (session was administratively revoked), 'logout' (user explicitly logged out). Use this to determine if the session can be used for new requests. + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp indicating when the session was last updated. Updated whenever session state changes such as organization context changes or metadata updates. + + - **`user_id`** + + `string` — Unique identifier for the user who owns and is authenticated within this session. + +* **`total_size`** + + `integer`, format: `int64` — Total number of sessions matching the applied filter criteria, regardless of pagination. This represents the complete result set size before pagination is applied. + +**Example:** + +```json +{ + "next_page_token": "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAic2VzXzEyMzQ1In0=", + "prev_page_token": "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInNlc183OTAxIn0=", + "sessions": [ + { + "absolute_expires_at": "2025-01-22T10:30:00Z", + "authenticated_clients": [ + {} + ], + "authenticated_organizations": [ + "org_123", + "org_456" + ], + "created_at": "2025-01-15T10:30:00Z", + "device": null, + "expired_at": "2025-01-15T12:00:00Z", + "idle_expires_at": "2025-01-15T11:30:00Z", + "last_active_at": "2025-01-15T10:55:30Z", + "logout_at": "2025-01-15T14:00:00Z", + "organization_id": "org_1234567890123456", + "session_id": "ses_1234567890123456", + "status": "active", + "updated_at": "2025-01-15T10:45:00Z", + "user_id": "usr_1234567890123456" + } + ], + "total_size": 42 +} +``` + +### sessionsUserSessionFilter + +- **Type:**`object` + +* **`end_time`** + + `string`, format: `date-time` — Filter to include only sessions created on or before this timestamp. Optional. Uses RFC 3339 format. Must be after start\_time if both are specified. + +* **`start_time`** + + `string`, format: `date-time` — Filter to include only sessions created on or after this timestamp. Optional. Uses RFC 3339 format. Useful for querying sessions within a specific time window. + +* **`status`** + + `array` — Filter sessions by one or more status values. Possible values: 'active', 'expired', 'revoked', 'logout'. Leave empty to include all statuses. Multiple values use OR logic (e.g., status=\['active', 'expired'] returns sessions that are either active OR expired). + + **Items:** + + `string` + +**Example:** + +```json +{ + "end_time": "2025-12-31T23:59:59Z", + "start_time": "2025-01-01T00:00:00Z", + "status": [ + "active" + ] +} +``` + +### toolsExecuteToolRequest + +- **Type:**`object` + +* **`connected_account_id`** + + `string` — Optional. The unique ID of the connected account. Use this to directly identify the connected account instead of using identifier + connector combination. + +* **`connector`** + + `string` — Optional. The name of the connector/provider (e.g., 'Google Workspace', 'Slack', 'Notion'). Use this in combination with identifier to identify the connected account. + +* **`identifier`** + + `string` — Optional. The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). Use this in combination with connector to identify the connected account. + +* **`organization_id`** + + `string` — Optional. The organization ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple organizations. + +* **`params`** + + `object` — JSON object containing the parameters required for tool execution. The structure depends on the specific tool being executed. + +* **`tool_name`** + + `string` — Name of the tool to execute + +* **`user_id`** + + `string` — Optional. The user ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple users. + +**Example:** + +```json +{ + "connected_account_id": "ca_123", + "connector": "Google Workspace", + "identifier": "user@example.com", + "organization_id": "org_123", + "params": { + "body": "Hello World", + "subject": "Hello", + "to": "user@example.com" + }, + "tool_name": "send_email", + "user_id": "user_123" +} +``` + +### toolsExecuteToolResponse + +- **Type:**`object` + +* **`data`** + + `object` — Free-flowing JSON parameters for the tool execution + +* **`execution_id`** + + `string` — Unique identifier for the tool execution + +**Example:** + +```json +{ + "data": { + "body": "Hello World", + "subject": "Hello", + "to": "user@example.com" + }, + "execution_id": "123456789" +} +``` + +### usersCreateMembershipResponse + +- **Type:**`object` + +* **`user`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "user": { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } +} +``` + +### usersCreateUser + +- **Type:**`object` + +* **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + +* **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + +* **`membership`** + + `object` — List of organization memberships. Automatically populated based on group assignments. + + - **`inviter_email`** + + `string` — Email address of the user who invited this member. Must be a valid email address. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`roles`** + + `array` — Role to assign to the user within the organization + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + +* **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + +* **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data. Keys (3-25 chars), values (1-256 chars). + + - **`family_name`** + + `string` — User's family name. Maximum 255 characters. + + - **`gender`** + + `string` — User's gender identity. + + - **`given_name`** + + `string` — User's given name. Maximum 255 characters. + + - **`groups`** + + `array` — List of group names the user belongs to. Each group name must be 1-250 characters + + **Items:** + + `string` + + - **`locale`** + + `string` — User's localization preference in BCP-47 format. Defaults to organization settings. + + - **`metadata`** + + `object` — System-managed key-value pairs for internal tracking. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Full name in display format. Typically combines first\_name and last\_name. + + - **`phone_number`** + + `string` — Phone number in E.164 international format. Required for SMS-based authentication. + + - **`picture`** + + `string` — URL to the user's profile picture or avatar. + + - **`preferred_username`** + + `string` — User's preferred username for display purposes. + +**Example:** + +```json +{ + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "membership": { + "inviter_email": "john.doe@example.com", + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "roles": [ + { + "name": "admin" + } + ] + }, + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "user_profile": { + "custom_attributes": { + "department": "engineering", + "security_clearance": "level2" + }, + "family_name": "Doe", + "gender": "male", + "given_name": "John", + "groups": [ + "engineering", + "managers" + ], + "locale": "en-US", + "metadata": { + "account_status": "active", + "signup_source": "mobile_app" + }, + "name": "John Michael Doe", + "phone_number": "+14155552671", + "picture": "https://example.com/avatar.jpg", + "preferred_username": "John Michael Doe" + } +} +``` + +### usersCreateUserAndMembershipResponse + +- **Type:**`object` + +* **`user`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "user": { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } +} +``` + +### usersCreateUserProfile + +- **Type:**`object` + +* **`custom_attributes`** + + `object` — Custom attributes for extended user profile data. Keys (3-25 chars), values (1-256 chars). + +* **`family_name`** + + `string` — User's family name. Maximum 255 characters. + +* **`gender`** + + `string` — User's gender identity. + +* **`given_name`** + + `string` — User's given name. Maximum 255 characters. + +* **`groups`** + + `array` — List of group names the user belongs to. Each group name must be 1-250 characters + + **Items:** + + `string` + +* **`locale`** + + `string` — User's localization preference in BCP-47 format. Defaults to organization settings. + +* **`metadata`** + + `object` — System-managed key-value pairs for internal tracking. Keys (3-25 chars), values (1-256 chars). + +* **`name`** + + `string` — Full name in display format. Typically combines first\_name and last\_name. + +* **`phone_number`** + + `string` — Phone number in E.164 international format. Required for SMS-based authentication. + +* **`picture`** + + `string` — URL to the user's profile picture or avatar. + +* **`preferred_username`** + + `string` — User's preferred username for display purposes. + +**Example:** + +```json +{ + "custom_attributes": { + "department": "engineering", + "security_clearance": "level2" + }, + "family_name": "Doe", + "gender": "male", + "given_name": "John", + "groups": [ + "engineering", + "managers" + ], + "locale": "en-US", + "metadata": { + "account_status": "active", + "signup_source": "mobile_app" + }, + "name": "John Michael Doe", + "phone_number": "+14155552671", + "picture": "https://example.com/avatar.jpg", + "preferred_username": "John Michael Doe" +} +``` + +### usersGetUserResponse + +- **Type:**`object` + +* **`user`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "user": { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } +} +``` + +### usersInvite + +- **Type:**`object` + +* **`created_at`** + + `string`, format: `date-time` — Timestamp when the invite was originally created. + +* **`expires_at`** + + `string`, format: `date-time` — The time at which the invite expires. + +* **`inviter_email`** + + `string` — Identifier of the user or system that initiated the invite. + +* **`organization_id`** + + `string` — The organization to which the invite belongs. + +* **`resent_at`** + + `string`, format: `date-time` — Timestamp when the invite was last resent, if applicable. + +* **`resent_count`** + + `integer`, format: `int32` — Number of times the invite has been resent. + +* **`status`** + + `string` — Current status of the invite (e.g., pending, accepted, expired, revoked). + +* **`user_id`** + + `string` — User ID to whom the invite is sent. May be empty if the user has not signed up yet. + +**Example:** + +```json +{ + "created_at": "2025-07-10T08:00:00Z", + "expires_at": "2025-12-31T23:59:59Z", + "inviter_email": "admin@example.com", + "organization_id": "org_987654321", + "resent_at": "2025-07-15T09:30:00Z", + "resent_count": 2, + "status": "pending_invite", + "user_id": "usr_123456" +} +``` + +### usersListOrganizationUsersResponse + +- **Type:**`object` + +* **`next_page_token`** + + `string` — Opaque token for retrieving the next page of results. Empty if there are no more pages. + +* **`prev_page_token`** + + `string` — Opaque token for retrieving the previous page of results. Empty for the first page. + +* **`total_size`** + + `integer`, format: `int64` — Total number of users matching the request criteria, regardless of pagination. + +* **`users`** + + `array` — List of user objects for the current page. May contain fewer entries than requested page\_size. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "next_page_token": "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=", + "prev_page_token": "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9", + "total_size": 1042, + "users": [ + { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } + ] +} +``` + +### usersListUserPermissionsResponse + +- **Type:**`object` + +* **`permissions`** + + `array` — List of permissions the user has access to + + **Items:** + + - **`description`** + + `string` — Description of what the permission allows + + - **`id`** + + `string` — Unique identifier for the permission + + - **`name`** + + `string` — Unique name identifier for the permission + +**Example:** + +```json +{ + "permissions": [ + { + "description": "Allows creating new user accounts", + "id": "perm_1234abcd5678efgh", + "name": "users:create" + } + ] +} +``` + +### usersListUserRolesResponse + +- **Type:**`object` + +* **`roles`** + + `array` — List of roles assigned to the user + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + +**Example:** + +```json +{ + "roles": [ + { + "display_name": "Dev Team", + "id": "role_79643236410327240", + "name": "team_dev" + } + ] +} +``` + +### usersListUsersResponse + +- **Type:**`object` + +* **`next_page_token`** + + `string` — Token for retrieving the next page of results. Empty if there are no more pages. + +* **`prev_page_token`** + + `string` — Token for retrieving the previous page of results. Empty if this is the first page. + +* **`total_size`** + + `integer`, format: `int64` — Total number of users matching the request criteria, regardless of pagination. + +* **`users`** + + `array` — List of users. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "next_page_token": "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=", + "prev_page_token": "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9", + "total_size": 1042, + "users": [ + { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } + ] +} +``` + +### usersPermission + +- **Type:**`object` + +* **`description`** + + `string` — Description of what the permission allows + +* **`id`** + + `string` — Unique identifier for the permission + +* **`name`** + + `string` — Unique name identifier for the permission + +**Example:** + +```json +{ + "description": "Allows creating new user accounts", + "id": "perm_1234abcd5678efgh", + "name": "users:create" +} +``` + +### usersResendInviteResponse + +- **Type:**`object` + +* **`invite`** + + `object` — Updated invitation object containing the resent invitation details, including new expiration time and incremented resend counter. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invite was originally created. + + - **`expires_at`** + + `string`, format: `date-time` — The time at which the invite expires. + + - **`inviter_email`** + + `string` — Identifier of the user or system that initiated the invite. + + - **`organization_id`** + + `string` — The organization to which the invite belongs. + + - **`resent_at`** + + `string`, format: `date-time` — Timestamp when the invite was last resent, if applicable. + + - **`resent_count`** + + `integer`, format: `int32` — Number of times the invite has been resent. + + - **`status`** + + `string` — Current status of the invite (e.g., pending, accepted, expired, revoked). + + - **`user_id`** + + `string` — User ID to whom the invite is sent. May be empty if the user has not signed up yet. + +**Example:** + +```json +{ + "invite": { + "expires_at": "2025-12-31T23:59:59Z", + "organization_id": "org_123", + "resent_count": 2, + "status": "pending_invite", + "user_id": "usr_456" + } +} +``` + +### usersSearchOrganizationUsersResponse + +- **Type:**`object` + +* **`next_page_token`** + + `string` — Token for retrieving the next page of results. Empty if there are no more pages. + +* **`prev_page_token`** + + `string` — Token for retrieving the previous page of results. Empty if this is the first page. + +* **`total_size`** + + `integer`, format: `int64` — Total number of users matching the request criteria, regardless of pagination. + +* **`users`** + + `array` — List of matching users. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "next_page_token": "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=", + "prev_page_token": "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9", + "total_size": 1042, + "users": [ + { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } + ] +} +``` + +### usersSearchUsersResponse + +- **Type:**`object` + +* **`next_page_token`** + + `string` — Token for retrieving the next page of results. Empty if there are no more pages. + +* **`prev_page_token`** + + `string` — Token for retrieving the previous page of results. Empty if this is the first page. + +* **`total_size`** + + `integer`, format: `int64` — Total number of users matching the request criteria, regardless of pagination. + +* **`users`** + + `array` — List of matching users. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "next_page_token": "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=", + "prev_page_token": "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9", + "total_size": 1042, + "users": [ + { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } + ] +} +``` + +### usersUpdateMembershipResponse + +- **Type:**`object` + +* **`user`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "user": { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } +} +``` + +### usersUpdateUserProfile + +- **Type:**`object` + +* **`custom_attributes`** + + `object` — Updates custom attributes for extended user profile data and application-specific information. Use this field to store business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + +* **`family_name`** + + `string` — Updates the user's family name (last name or surname). Use this field to modify how the user's last name appears throughout the system. Maximum 255 characters allowed. + +* **`first_name`** + + `string` — \[DEPRECATED] Use given\_name instead. User's given name. Maximum 200 characters. + +* **`gender`** + + `string` — Updates the user's gender identity information. Use this field to store the user's gender identity for personalization, compliance, or reporting purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies. + +* **`given_name`** + + `string` — Updates the user's given name (first name). Use this field to modify how the user's first name appears in the system and user interfaces. Maximum 255 characters allowed. + +* **`groups`** + + `array` — Updates the list of group names the user belongs to within the organization. Use this field to manage the user's group memberships for role-based access control, team assignments, or organizational structure. Groups are typically used for permission management and collaborative access. Each group name must be unique within the list, 1-250 characters long, with a maximum of 50 groups per user. + + **Items:** + + `string` + +* **`last_name`** + + `string` — \[DEPRECATED] Use family\_name instead. User's family name. Maximum 200 characters. + +* **`locale`** + + `string` — Updates the user's preferred language and region settings using BCP-47 format codes. Use this field to customize the user's experience with localized content, date formats, number formatting, and UI language. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + +* **`metadata`** + + `object` — Updates system-managed key-value pairs for internal tracking and operational data. Use this field to store system-generated metadata like account status, signup source, last activity tracking, or integration-specific identifiers. These fields are typically managed by automated processes rather than direct user input. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + +* **`name`** + + `string` — Updates the user's complete display name. Use this field when you want to set the full name as a single string rather than using separate given and family names. This name appears in user interfaces, reports, and anywhere a formatted display name is needed. + +* **`phone_number`** + + `string` — Updates the user's phone number in E.164 international format. Use this field to enable SMS-based authentication methods, two-factor authentication, or phone-based account recovery. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is required when enabling SMS authentication features. + +* **`picture`** + + `string` — Updates the URL to the user's profile picture or avatar image. Use this field to set or change the user's profile photo that appears in user interfaces, directory listings, and collaborative features. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. Maximum URL length is 2048 characters. + +* **`preferred_username`** + + `string` — Updates the user's preferred username for display and identification purposes. Use this field to set a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, and informal communications. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "custom_attributes": { + "department": "engineering", + "security_clearance": "level2" + }, + "family_name": "Doe", + "first_name": "John", + "gender": "male", + "given_name": "John", + "groups": [ + "engineering", + "managers" + ], + "last_name": "Doe", + "locale": "en-US", + "metadata": { + "account_status": "active", + "signup_source": "mobile_app" + }, + "name": "John Doe", + "phone_number": "+14155552671", + "picture": "https://example.com/avatar.jpg", + "preferred_username": "John Michael Doe" +} +``` + +### usersUpdateUserResponse + +- **Type:**`object` + +* **`user`** + + `object` + + - **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + + - **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + + - **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + + - **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + + - **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + + - **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "user": { + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + {} + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": null + } +} +``` + +### usersUser + +- **Type:**`object` + +* **`create_time`** + + `string`, format: `date-time` — Timestamp when the user account was initially created. Automatically set by the server. + +* **`email`** + + `string` — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. + +* **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + +* **`id`** + + `string` — Unique system-generated identifier for the user. Immutable once created. + +* **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's most recent successful authentication. Updated automatically. + +* **`memberships`** + + `array` — List of organization memberships. Automatically populated based on group assignments. + + **Items:** + + - **`accepted_at`** + + `string`, format: `date-time` — Timestamp when the user accepted the invitation. + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the invitation was created. + + - **`display_name`** + + `string` — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. + + - **`expires_at`** + + `string`, format: `date-time` — Timestamp when the invitation expired. + + - **`inviter_email`** + + `string` — ID of the user who invited this user. + + - **`join_time`** + + `string`, format: `date-time` — Timestamp when the membership was created. Automatically set by the server. + + - **`membership_status`** + + `string`, possible values: `"ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED"` + + - **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + + - **`name`** + + `string` — Organization name. This field stores the formal organization name used for identification and display purposes. + + - **`organization_id`** + + `string` — Unique identifier for the organization. Immutable and read-only. + + - **`permissions`** + + `array` — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. + + **Items:** + + `string` + + - **`provisioning_method`** + + `string` — How the user was provisioned. Possible values: - \`jit\_using\_sso\` (Just-in-time provisioning during SSO login) - \`allowed\_email\_domain\` (User joined via allowed email domain matching) - \`org\_creator\` (User created the organization) - \`direct\_provision\` (User was directly provisioned via API or SCIM) - \`invitation\` (User was invited and accepted an invitation) + + - **`roles`** + + `array` + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + +* **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + +* **`update_time`** + + `string`, format: `date-time` — Timestamp of the last modification to the user account. Automatically updated by the server. + +* **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`email_verified`** + + `boolean` — Indicates if the user's email address has been verified. Automatically updated by the system. + + - **`external_identities`** + + `array` — List of external identity connections associated with the user profile. + + **Items:** + + - **`connection_id`** + + `string` — Unique identifier for the external identity connection. Immutable and read-only. + + - **`connection_provider`** + + `string`, possible values: `"OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS"` — Type of the identity provider. + + - **`connection_type`** + + `string` — Name of the external identity connection. + + - **`connection_user_id`** + + `string` — Unique identifier for the user in the external identity provider system. Immutable and read-only. + + - **`created_time`** + + `string`, format: `date-time` — Timestamp when this external identity connection was first created. Immutable and read-only. + + - **`is_social`** + + `boolean` — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. + + - **`last_login_time`** + + `string`, format: `date-time` — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. + + - **`last_synced_time`** + + `string`, format: `date-time` — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. + + - **`family_name`** + + `string` — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. + + - **`gender`** + + `string` — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. + + - **`given_name`** + + `string` — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. + + - **`groups`** + + `array` — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. + + **Items:** + + `string` + + - **`id`** + + `string` — Unique system-generated identifier for the user profile. Immutable and read-only. + + - **`locale`** + + `string` — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given\_name and family\_name fields. + + - **`phone_number`** + + `string` — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is optional. + + - **`phone_number_verified`** + + `boolean` — Indicates if the user's phone number has been verified. Automatically updated by the system. + + - **`picture`** + + `string` — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. + + - **`preferred_username`** + + `string` — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "create_time": "", + "email": "user@example.com", + "external_id": "ext_12345a67b89c", + "id": "usr_1234abcd5678efgh", + "last_login_time": "", + "memberships": [ + { + "accepted_at": "", + "created_at": "", + "display_name": "Acme Corporation", + "expires_at": "", + "inviter_email": "", + "join_time": "", + "membership_status": null, + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "name": "AcmeCorp", + "organization_id": "org_1234abcd5678efgh", + "permissions": [ + "read_projects", + "write_tasks", + "manage_users" + ], + "provisioning_method": "", + "roles": [ + {} + ] + } + ], + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "update_time": "", + "user_profile": { + "custom_attributes": { + "department": "engineering", + "security_clearance": "level2" + }, + "email_verified": true, + "external_identities": [ + {} + ], + "family_name": "Doe", + "gender": "male", + "given_name": "John", + "groups": [ + "admin", + "developer" + ], + "id": "usr_profile_1234abcd5678efgh", + "locale": "en-US", + "metadata": { + "department": "engineering", + "employee_type": "full-time", + "idp_user_id": "12345" + }, + "name": "John Michael Doe", + "phone_number": "+14155552671", + "phone_number_verified": true, + "picture": "https://example.com/avatar.jpg", + "preferred_username": "johndoe" + } +} +``` + +### Payload for creating a new connected account - authorization details are optional + +- **Type:**`object` + +* **`api_config`** + + `object` — Optional JSON configuration for connector-specific API settings such as rate limits, custom API endpoints, timeouts, or feature flags. + +* **`authorization_details`** + + `object` — Optional authentication credentials for the connected account. Include OAuth tokens (access\_token, refresh\_token, scopes) or static auth details (API keys, bearer tokens). Can be provided later via update. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +**Example:** + +```json +{ + "api_config": { + "base_url": "https://api.custom-domain.com", + "rate_limit": 1000, + "timeout": 30 + }, + "authorization_details": { + "oauth_token": { + "access_token": "ya29.a0...", + "refresh_token": "1//0g...", + "scopes": [ + "email", + "profile" + ] + } + } +} +``` + +### Payload for updating an existing connected account - all fields optional + +- **Type:**`object` + +* **`api_config`** + + `object` — Updated JSON configuration for API-specific settings. Merges with existing configuration - only provided fields are modified. + +* **`authorization_details`** + + `object` — Updated authentication credentials. Provide new OAuth tokens (e.g., after refresh) or updated static auth details. Only included fields will be modified. + + - **`oauth_token`** + + `object` + + - **`access_token`** + + `string` — OAuth access token for API requests. Typically short-lived and must be refreshed after expiration. + + - **`domain`** + + `string` — Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain). + + - **`refresh_token`** + + `string` — OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization. + + - **`scopes`** + + `array` — List of granted OAuth scopes defining the permissions and access levels for this connection. + + **Items:** + + `string` + + - **`static_auth`** + + `object` + + - **`details`** + + `object` — Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.). + +**Example:** + +```json +{ + "api_config": { + "rate_limit": 2000, + "timeout": 60 + }, + "authorization_details": { + "oauth_token": { + "access_token": "ya29.new_token...", + "refresh_token": "1//0g...", + "scopes": [ + "email", + "profile", + "calendar" + ] + } + } +} +``` + +### v1domainsCreateDomain + +- **Type:**`object` + +* **`domain`** + + `string` — The domain name to be configured. Must be a valid business domain you control. Public and disposable domains (gmail.com, outlook.com, etc.) are automatically blocked for security. + +* **`domain_type`** + + `string`, possible values: `"ALLOWED_EMAIL_DOMAIN", "ORGANIZATION_DOMAIN"` — The domain type. - ALLOWED\_EMAIL\_DOMAIN: trusted domain used to suggest the organization in the organization switcher during sign-in/sign-up. - ORGANIZATION\_DOMAIN: SSO discovery domain used to route users to the correct SSO provider and enforce SSO. + +**Example:** + +```json +{ + "domain": "customerdomain.com", + "domain_type": "ORGANIZATION_DOMAIN" +} +``` + +### v1organizationsCreateOrganization + +- **Type:**`object` + +* **`display_name` (required)** + + `string` — Name of the organization. Must be between 1 and 200 characters. + +* **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + +* **`metadata`** + + `object` + +**Example:** + +```json +{ + "display_name": "Megasoft Inc", + "external_id": "my_unique_id", + "metadata": { + "additionalProperty": "" + } +} +``` + +### v1organizationsUpdateOrganization + +- **Type:**`object` + +For update messages ensure the indexes are same as the base model itself. + +- **`display_name`** + + `string` — Name of the organization to display in the UI. Must be between 1 and 200 characters + +- **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system + +- **`metadata`** + + `object` — Custom key-value pairs to store with the organization. Keys must be 3-25 characters, values must be 1-256 characters. Maximum 10 pairs allowed. + +**Example:** + +```json +{ + "display_name": "Acme Corporation", + "external_id": "tenant_12345", + "metadata": { + "industry": "technology" + } +} +``` + +### v1rolesCreateOrganizationRole + +- **Type:**`object` + +* **`description`** + + `string` — Description of the organization's role + +* **`display_name`** + + `string` — Display name of the organization's role + +* **`extends`** + + `string` — Base role name for hierarchical roles + +* **`name`** + + `string` — Unique name of the organization's role + +* **`permissions`** + + `array` — List of permission names to assign to this role. Permissions must exist in the current environment. + + **Items:** + + `string` + +**Example:** + +```json +{ + "description": "Organization Viewer Role will be used only for viewing the objects", + "display_name": "Organization Viewer Role", + "extends": "admin_role", + "name": "org_viewer_role", + "permissions": [ + "read:users", + "write:documents" + ] +} +``` + +### v1rolesCreatePermission + +- **Type:**`object` + +* **`description`** + + `string` — Description of the permission + +* **`name`** + + `string` — Unique name/ID of the permission + +**Example:** + +```json +{ + "description": "Allows user to read documents from the system", + "name": "read:documents" +} +``` + +### v1rolesCreateRole + +- **Type:**`object` + +* **`description`** + + `string` — Detailed description of the role's purpose, capabilities, and intended use cases. Maximum 2000 characters. + +* **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces, reports, and user-facing communications. + +* **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance where this role inherits all permissions from the base role. + +* **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-64 characters. This name is used in API calls and cannot be changed after creation. + +* **`permissions`** + + `array` — List of permission names to assign to this role. Permissions must exist in the current environment. Maximum 100 permissions per role. + + **Items:** + + `string` + +**Example:** + +```json +{ + "description": "Can create, edit, and publish content but cannot delete content or manage user accounts", + "display_name": "Content Editor", + "extends": "viewer", + "name": "content_editor", + "permissions": [ + "read:content", + "write:content", + "publish:content" + ] +} +``` + +### v1rolesRole + +- **Type:**`object` + +* **`default_creator`** + + `boolean` — Indicates if this role is the default creator role for new organizations. + +* **`default_member`** + + `boolean` — Indicates if this role is the default member role for new users. + +* **`dependent_roles_count`** + + `integer`, format: `int32` — Number of roles that extend from this role (dependent roles count). Read-only field. + +* **`description`** + + `string` — Detailed description of the role's purpose and capabilities. Maximum 2000 characters. + +* **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces and reports. + +* **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance. + +* **`id`** + + `string` — Unique system-generated identifier for the role. Immutable once created. + +* **`is_org_role`** + + `boolean` — Indicates if this role is an organization role. + +* **`name`** + + `string` — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters. + +* **`permissions`** + + `array` — List of permissions with role source information. Only included when 'include' parameter is specified in the request. + + **Items:** + + - **`create_time`** + + `string`, format: `date-time` + + - **`description`** + + `string` + + - **`id`** + + `string` + + - **`name`** + + `string` + + - **`role_name`** + + `string` — Name of the role from which this permission was sourced + + - **`update_time`** + + `string`, format: `date-time` + +**Example:** + +```json +{ + "default_creator": true, + "default_member": true, + "dependent_roles_count": 3, + "description": "Can create, edit, and publish content but cannot delete or manage users", + "display_name": "Content Editor", + "extends": "admin_role", + "id": "role_1234abcd5678efgh", + "is_org_role": true, + "name": "content_editor", + "permissions": [ + { + "description": "Read Content", + "name": "read:content", + "role_name": "admin_role" + }, + { + "description": "Write Content", + "name": "write:content", + "role_name": "editor_role" + } + ] +} +``` + +### v1rolesUpdateRole + +- **Type:**`object` + +* **`description`** + + `string` — Detailed description of the role's purpose, capabilities, and intended use cases. Maximum 2000 characters. + +* **`display_name`** + + `string` — Human-readable display name for the role. Used in user interfaces, reports, and user-facing communications. + +* **`extends`** + + `string` — Name of the base role that this role extends. Enables hierarchical role inheritance where this role inherits all permissions from the base role. + +* **`permissions`** + + `array` — List of permission names to assign to this role. When provided, this replaces all existing role-permission mappings. Permissions must exist in the current environment. Maximum 100 permissions per role. + + **Items:** + + `string` + +**Example:** + +```json +{ + "description": "Can create, edit, publish, and approve content. Cannot delete content or manage user accounts.", + "display_name": "Senior Content Editor", + "extends": "content_editor", + "permissions": [ + "read:content", + "write:content", + "publish:content", + "approve:content" + ] +} +``` + +### v1sessionsLocation + +- **Type:**`object` + +* **`city`** + + `string` — City name where the session originated based on IP geolocation. Approximate location derived from IP address. + +* **`latitude`** + + `string` — Latitude coordinate of the estimated location. Decimal format (e.g., '37.7749'). Note: Represents IP geolocation center and may not be precise. + +* **`longitude`** + + `string` — Longitude coordinate of the estimated location. Decimal format (e.g., '-122.4194'). Note: Represents IP geolocation center and may not be precise. + +* **`region`** + + `string` — Geographic region name derived from IP geolocation. Represents the country-level location (e.g., 'United States', 'France'). + +* **`region_subdivision`** + + `string` — Regional subdivision code or name (e.g., state abbreviation for US, province for Canada). Two-letter ISO format when applicable. + +**Example:** + +```json +{ + "city": "San Francisco", + "latitude": "37.7749", + "longitude": "-122.4194", + "region": "United States", + "region_subdivision": "CA" +} +``` + +### v1usersCreateMembership + +- **Type:**`object` + +* **`inviter_email`** + + `string` — Email address of the user who invited this member. Must be a valid email address. + +* **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + +* **`roles`** + + `array` — Role to assign to the user within the organization + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + +**Example:** + +```json +{ + "inviter_email": "john.doe@example.com", + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "roles": [ + { + "name": "admin" + } + ] +} +``` + +### v1usersUpdateMembership + +- **Type:**`object` + +* **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + +* **`roles`** + + `array` — Role to assign to the user within the organization + + **Items:** + + - **`display_name`** + + `string` — Human-readable name for the role + + - **`id`** + + `string` — Role ID + + - **`name`** + + `string` — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. + +**Example:** + +```json +{ + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "roles": [ + { + "name": "admin" + } + ] +} +``` + +### v1usersUpdateUser + +- **Type:**`object` + +* **`external_id`** + + `string` — Your application's unique identifier for this organization, used to link Scalekit with your system. + +* **`metadata`** + + `object` — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). + +* **`user_profile`** + + `object` — User's personal information including name, address, and other profile attributes. + + - **`custom_attributes`** + + `object` — Updates custom attributes for extended user profile data and application-specific information. Use this field to store business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`family_name`** + + `string` — Updates the user's family name (last name or surname). Use this field to modify how the user's last name appears throughout the system. Maximum 255 characters allowed. + + - **`first_name`** + + `string` — \[DEPRECATED] Use given\_name instead. User's given name. Maximum 200 characters. + + - **`gender`** + + `string` — Updates the user's gender identity information. Use this field to store the user's gender identity for personalization, compliance, or reporting purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies. + + - **`given_name`** + + `string` — Updates the user's given name (first name). Use this field to modify how the user's first name appears in the system and user interfaces. Maximum 255 characters allowed. + + - **`groups`** + + `array` — Updates the list of group names the user belongs to within the organization. Use this field to manage the user's group memberships for role-based access control, team assignments, or organizational structure. Groups are typically used for permission management and collaborative access. Each group name must be unique within the list, 1-250 characters long, with a maximum of 50 groups per user. + + **Items:** + + `string` + + - **`last_name`** + + `string` — \[DEPRECATED] Use family\_name instead. User's family name. Maximum 200 characters. + + - **`locale`** + + `string` — Updates the user's preferred language and region settings using BCP-47 format codes. Use this field to customize the user's experience with localized content, date formats, number formatting, and UI language. When not specified, the user inherits the organization's default locale settings. Common values include \`en-US\`, \`en-GB\`, \`fr-FR\`, \`de-DE\`, and \`es-ES\`. + + - **`metadata`** + + `object` — Updates system-managed key-value pairs for internal tracking and operational data. Use this field to store system-generated metadata like account status, signup source, last activity tracking, or integration-specific identifiers. These fields are typically managed by automated processes rather than direct user input. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. + + - **`name`** + + `string` — Updates the user's complete display name. Use this field when you want to set the full name as a single string rather than using separate given and family names. This name appears in user interfaces, reports, and anywhere a formatted display name is needed. + + - **`phone_number`** + + `string` — Updates the user's phone number in E.164 international format. Use this field to enable SMS-based authentication methods, two-factor authentication, or phone-based account recovery. The phone number must include the country code and be formatted according to E.164 standards (e.g., \`+1\` for US numbers). This field is required when enabling SMS authentication features. + + - **`picture`** + + `string` — Updates the URL to the user's profile picture or avatar image. Use this field to set or change the user's profile photo that appears in user interfaces, directory listings, and collaborative features. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. Maximum URL length is 2048 characters. + + - **`preferred_username`** + + `string` — Updates the user's preferred username for display and identification purposes. Use this field to set a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, and informal communications. Maximum 512 characters allowed. + +**Example:** + +```json +{ + "external_id": "ext_12345a67b89c", + "metadata": { + "department": "engineering", + "location": "nyc-office" + }, + "user_profile": { + "custom_attributes": { + "department": "engineering", + "security_clearance": "level2" + }, + "family_name": "Doe", + "first_name": "John", + "gender": "male", + "given_name": "John", + "groups": [ + "engineering", + "managers" + ], + "last_name": "Doe", + "locale": "en-US", + "metadata": { + "account_status": "active", + "signup_source": "mobile_app" + }, + "name": "John Doe", + "phone_number": "+14155552671", + "picture": "https://example.com/avatar.jpg", + "preferred_username": "John Michael Doe" + } +} +``` + +### webauthnAllAcceptedCredentialsOptions + +- **Type:**`object` + +* **`all_accepted_credential_ids`** + + `array` — List of credential IDs the user can authenticate with + + **Items:** + + `string` + +* **`rp_id`** + + `string` — Relying Party ID for credential operations + +* **`user_id`** + + `string` — User ID for credential verification + +**Example:** + +```json +{ + "all_accepted_credential_ids": [ + "" + ], + "rp_id": "example.com", + "user_id": "user_xyz789" +} +``` + +### webauthnDeleteCredentialResponse + +- **Type:**`object` + +* **`success`** + + `boolean` — Whether the credential was successfully deleted + +* **`unknown_credential_options`** + + `object` — Options for handling unknown credentials in client applications + + - **`credential_id`** + + `string` — The deleted credential ID + + - **`rp_id`** + + `string` — The RP ID for this credential + +**Example:** + +```json +{ + "success": true, + "unknown_credential_options": { + "credential_id": "cred_abc123", + "rp_id": "example.com" + } +} +``` + +### webauthnListCredentialsResponse + +- **Type:**`object` + +* **`all_accepted_credentials_options`** + + `object` — Options including RP ID and all accepted credential IDs for authentication + + - **`all_accepted_credential_ids`** + + `array` — List of credential IDs the user can authenticate with + + **Items:** + + `string` + + - **`rp_id`** + + `string` — Relying Party ID for credential operations + + - **`user_id`** + + `string` — User ID for credential verification + +* **`credentials`** + + `array` — All passkeys registered for the user + + **Items:** + + - **`attestation_type`** + + `string` — Type of attestation: "none", "indirect", or "direct" + + - **`authenticator`** + + `object` — Authenticator information including model and name + + - **`aaguid`** + + `string` — Authenticator Attestation GUID (AAGUID) identifying the device model + + - **`attachment`** + + `string` — Attachment type: "platform" (built-in) or "cross-platform" + + - **`icon_dark`** + + `string` — Icon URL for dark theme display + + - **`icon_light`** + + `string` — Icon URL for light theme display + + - **`name`** + + `string` — Human-readable name of the authenticator model + + - **`authenticator_flags`** + + `object` — Flags indicating authenticator capabilities + + - **`backup_eligible`** + + `boolean` — Whether this credential can be backed up to another device + + - **`backup_state`** + + `boolean` — Whether this credential was synced or backed up + + - **`user_present`** + + `boolean` — Whether the user was present during authentication + + - **`user_verified`** + + `boolean` — Whether the user was verified (e.g., fingerprint, PIN) + + - **`client_info`** + + `object` — Geographic and network information from registration + + - **`city`** + + `string` — City name + + - **`ip`** + + `string` — IP address from which credential was registered + + - **`region`** + + `string` — Geographic region (e.g., "US") + + - **`region_subdivision`** + + `string` — Regional subdivision (e.g., "CA") + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the credential was created + + - **`credential_id`** + + `string` — The actual credential ID bytes from the authenticator + + - **`display_name`** + + `string` — Optional user-friendly name for this passkey + + - **`id`** + + `string` — Credential unique identifier + + - **`transports`** + + `array` — Supported transports for this credential + + **Items:** + + `string` + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp of last update + + - **`user_agent`** + + `object` — Browser and device information from registration + + - **`browser`** + + `string` — Browser name (e.g., "Chrome", "Safari") + + - **`browser_version`** + + `string` — Browser version number + + - **`device_model`** + + `string` — Device model if available + + - **`device_type`** + + `string` — Device type: "desktop", "mobile", or "tablet" + + - **`os`** + + `string` — Operating system name (e.g., "Windows", "iOS") + + - **`os_version`** + + `string` — Operating system version + + - **`raw`** + + `string` — Raw user agent string from the browser + + - **`url`** + + `string` — Parsed user agent URL reference + + - **`user_id`** + + `string` — User ID this credential belongs to + +**Example:** + +```json +{ + "all_accepted_credentials_options": { + "all_accepted_credential_ids": [ + "" + ], + "rp_id": "example.com", + "user_id": "user_xyz789" + }, + "credentials": [ + { + "attestation_type": "direct", + "authenticator": null, + "authenticator_flags": null, + "client_info": null, + "created_at": "2025-02-15T06:23:44.560000Z", + "credential_id": "", + "display_name": "My Yubikey", + "id": "cred_abc123", + "transports": [ + "" + ], + "updated_at": "2025-02-15T06:23:44.560000Z", + "user_agent": null, + "user_id": "user_xyz789" + } + ] +} +``` + +### webauthnUnknownCredentialOptions + +- **Type:**`object` + +* **`credential_id`** + + `string` — The deleted credential ID + +* **`rp_id`** + + `string` — The RP ID for this credential + +**Example:** + +```json +{ + "credential_id": "cred_abc123", + "rp_id": "example.com" +} +``` + +### webauthnUpdateCredentialResponse + +- **Type:**`object` + +* **`credential`** + + `object` — The updated credential with new display name + + - **`attestation_type`** + + `string` — Type of attestation: "none", "indirect", or "direct" + + - **`authenticator`** + + `object` — Authenticator information including model and name + + - **`aaguid`** + + `string` — Authenticator Attestation GUID (AAGUID) identifying the device model + + - **`attachment`** + + `string` — Attachment type: "platform" (built-in) or "cross-platform" + + - **`icon_dark`** + + `string` — Icon URL for dark theme display + + - **`icon_light`** + + `string` — Icon URL for light theme display + + - **`name`** + + `string` — Human-readable name of the authenticator model + + - **`authenticator_flags`** + + `object` — Flags indicating authenticator capabilities + + - **`backup_eligible`** + + `boolean` — Whether this credential can be backed up to another device + + - **`backup_state`** + + `boolean` — Whether this credential was synced or backed up + + - **`user_present`** + + `boolean` — Whether the user was present during authentication + + - **`user_verified`** + + `boolean` — Whether the user was verified (e.g., fingerprint, PIN) + + - **`client_info`** + + `object` — Geographic and network information from registration + + - **`city`** + + `string` — City name + + - **`ip`** + + `string` — IP address from which credential was registered + + - **`region`** + + `string` — Geographic region (e.g., "US") + + - **`region_subdivision`** + + `string` — Regional subdivision (e.g., "CA") + + - **`created_at`** + + `string`, format: `date-time` — Timestamp when the credential was created + + - **`credential_id`** + + `string` — The actual credential ID bytes from the authenticator + + - **`display_name`** + + `string` — Optional user-friendly name for this passkey + + - **`id`** + + `string` — Credential unique identifier + + - **`transports`** + + `array` — Supported transports for this credential + + **Items:** + + `string` + + - **`updated_at`** + + `string`, format: `date-time` — Timestamp of last update + + - **`user_agent`** + + `object` — Browser and device information from registration + + - **`browser`** + + `string` — Browser name (e.g., "Chrome", "Safari") + + - **`browser_version`** + + `string` — Browser version number + + - **`device_model`** + + `string` — Device model if available + + - **`device_type`** + + `string` — Device type: "desktop", "mobile", or "tablet" + + - **`os`** + + `string` — Operating system name (e.g., "Windows", "iOS") + + - **`os_version`** + + `string` — Operating system version + + - **`raw`** + + `string` — Raw user agent string from the browser + + - **`url`** + + `string` — Parsed user agent URL reference + + - **`user_id`** + + `string` — User ID this credential belongs to + +**Example:** + +```json +{ + "credential": { + "attestation_type": "direct", + "authenticator": null, + "authenticator_flags": null, + "client_info": null, + "created_at": "2025-02-15T06:23:44.560000Z", + "credential_id": "", + "display_name": "My Yubikey", + "id": "cred_abc123", + "transports": [ + "" + ], + "updated_at": "2025-02-15T06:23:44.560000Z", + "user_agent": null, + "user_id": "user_xyz789" + } +} +``` + +### webauthnWebAuthnCredential + +- **Type:**`object` + +* **`attestation_type`** + + `string` — Type of attestation: "none", "indirect", or "direct" + +* **`authenticator`** + + `object` — Authenticator information including model and name + + - **`aaguid`** + + `string` — Authenticator Attestation GUID (AAGUID) identifying the device model + + - **`attachment`** + + `string` — Attachment type: "platform" (built-in) or "cross-platform" + + - **`icon_dark`** + + `string` — Icon URL for dark theme display + + - **`icon_light`** + + `string` — Icon URL for light theme display + + - **`name`** + + `string` — Human-readable name of the authenticator model + +* **`authenticator_flags`** + + `object` — Flags indicating authenticator capabilities + + - **`backup_eligible`** + + `boolean` — Whether this credential can be backed up to another device + + - **`backup_state`** + + `boolean` — Whether this credential was synced or backed up + + - **`user_present`** + + `boolean` — Whether the user was present during authentication + + - **`user_verified`** + + `boolean` — Whether the user was verified (e.g., fingerprint, PIN) + +* **`client_info`** + + `object` — Geographic and network information from registration + + - **`city`** + + `string` — City name + + - **`ip`** + + `string` — IP address from which credential was registered + + - **`region`** + + `string` — Geographic region (e.g., "US") + + - **`region_subdivision`** + + `string` — Regional subdivision (e.g., "CA") + +* **`created_at`** + + `string`, format: `date-time` — Timestamp when the credential was created + +* **`credential_id`** + + `string` — The actual credential ID bytes from the authenticator + +* **`display_name`** + + `string` — Optional user-friendly name for this passkey + +* **`id`** + + `string` — Credential unique identifier + +* **`transports`** + + `array` — Supported transports for this credential + + **Items:** + + `string` + +* **`updated_at`** + + `string`, format: `date-time` — Timestamp of last update + +* **`user_agent`** + + `object` — Browser and device information from registration + + - **`browser`** + + `string` — Browser name (e.g., "Chrome", "Safari") + + - **`browser_version`** + + `string` — Browser version number + + - **`device_model`** + + `string` — Device model if available + + - **`device_type`** + + `string` — Device type: "desktop", "mobile", or "tablet" + + - **`os`** + + `string` — Operating system name (e.g., "Windows", "iOS") + + - **`os_version`** + + `string` — Operating system version + + - **`raw`** + + `string` — Raw user agent string from the browser + + - **`url`** + + `string` — Parsed user agent URL reference + +* **`user_id`** + + `string` — User ID this credential belongs to + +**Example:** + +```json +{ + "attestation_type": "direct", + "authenticator": { + "aaguid": "", + "attachment": "platform", + "icon_dark": "", + "icon_light": "", + "name": "Apple Touch ID" + }, + "authenticator_flags": { + "backup_eligible": true, + "backup_state": true, + "user_present": true, + "user_verified": true + }, + "client_info": { + "city": "San Francisco", + "ip": "192.0.2.1", + "region": "US", + "region_subdivision": "CA" + }, + "created_at": "2025-02-15T06:23:44.560000Z", + "credential_id": "", + "display_name": "My Yubikey", + "id": "cred_abc123", + "transports": [ + "" + ], + "updated_at": "2025-02-15T06:23:44.560000Z", + "user_agent": { + "browser": "Chrome", + "browser_version": "120.0.6099.129", + "device_model": "iPhone15,2", + "device_type": "mobile", + "os": "macOS", + "os_version": "14.2", + "raw": "", + "url": "" + }, + "user_id": "user_xyz789" +} +``` + +### ScalekitEvent + +- **Type:**`object` + +* **`environment_id` (required)** + + `string` — The environment ID where the event occurred + +* **`id` (required)** + + `string` — Unique identifier for the webhook event (must be prefixed with "evt\_") + +* **`object` (required)** + + `string`, possible values: `"Organization", "Connection", "Role", "Directory", "DirectoryUser", "DirectoryGroup", "Permission", "OrgMembership", "User"` — The type of object that triggered the webhook + +* **`occurred_at` (required)** + + `string`, format: `date-time` — When the event occurred (ISO 8601 format) + +* **`spec_version` (required)** + + `string` — The webhook specification version + +* **`type` (required)** + + `string`, possible values: `"organization.created", "organization.updated", "organization.deleted", "organization.sso_created", "organization.sso_deleted", "organization.sso_enabled", "organization.sso_disabled", "user.signup", "user.login", "user.logout", "user.organization_invitation", "user.organization_membership_created", "user.organization_membership_updated", "user.organization_membership_deleted", "organization.directory.user_created", "organization.directory.user_updated", "organization.directory.user_deleted", "organization.directory.group_created", "organization.directory.group_updated", "organization.directory.group_deleted", "organization.directory_enabled", "organization.directory_disabled", "role.created", "role.updated", "role.deleted", "permission.created", "permission.updated", "permission.deleted"` — The event type + +* **`data`** + + `object` — The event payload (structure varies by event type) + +* **`display_name`** + + `string` — Human-readable display name for the event + +* **`organization_id`** + + `string` — The organization ID (if applicable) + +**Example:** + +```json +{ + "spec_version": "1", + "id": "evt_1234567890abcdef", + "type": "organization.created", + "occurred_at": "2024-01-01T00:00:00Z", + "environment_id": "env_1234567890abcdef", + "organization_id": "org_1234567890abcdef", + "object": "Organization", + "data": { + "id": "org_1234567890abcdef", + "name": "Example Organization", + "created_at": "2024-01-01T00:00:00Z" + }, + "display_name": "Organization Created" +} +``` diff --git a/public/d2/docs/cookbooks/litellm-agentkit-inbox-triage-0.svg b/public/d2/docs/cookbooks/litellm-agentkit-inbox-triage-0.svg index afa63f056..abffc50ef 100644 --- a/public/d2/docs/cookbooks/litellm-agentkit-inbox-triage-0.svg +++ b/public/d2/docs/cookbooks/litellm-agentkit-inbox-triage-0.svg @@ -1,4 +1,4 @@ -