CreateIntegration

POST/api/v1/integrations

Connect an integration, which starts syncing the resources and accounts it can see. Users who aren’t admins may create one with an install link.

Example request

US
Europe

curl -X POST \
  -H "Authorization: Bearer ${OBLIQUE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "displayName": "string", "clientId": "string", "clientSecret": "string", "installLinkValue": "string" }' \
  "https://us.oblique.security/api/v1/integrations"

Set OBLIQUE_API_KEY to your API key.

curl -X POST \
  -H "Authorization: Bearer ${OBLIQUE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "displayName": "string", "clientId": "string", "clientSecret": "string", "installLinkValue": "string" }' \
  "https://eu.oblique.security/api/v1/integrations"

Set OBLIQUE_API_KEY to your API key.

Query parameters

integrationIdstring
ID of the integration to create. This value should be 4-63 characters. Valid characters are /[a-z][0-9]-/.

Request body

namestring
Assigned by Oblique. Name of the integration of the format integrations/{integration}.
managementManagement
How this integration is managed. Set automatically by the server based on the calling client. Omitted from responses when the integration is manually managed (the default).
- managerstring
  Allowed values: TERRAFORM
  How the API object is managed. Set automatically by the server based on the caller: Terraform clients produce TERRAFORM; for all other clients the management field is left unset on the response.
- repoUristring
  URI of the VCS repository that holds the Terraform configuration for this API object. Populated by the Oblique Terraform provider.
- repoDirstring
  Optionally, the subdirectory within repo_uri that holds the Terraform configuration for this API object. Populated by the Oblique Terraform provider.
displayNamestring
A human readable name of the integration. For example “Okta Test”.
createTimestring (date-time)read-only
Create and update timestamps.
updateTimestring (date-time)read-only
deleteTimestring (date-time)read-only
The time when the integration was deleted.
credentialUpdateTimestring (date-time)read-only
The time a person last connected new credentials for the integration, for example by adding it, reauthorizing it, or reinstalling its app. Automatic token refreshes don’t change it.
clientIdstring
The ID of the OAuth client the integration authenticates with for integrations like Tailscale and 1Password. Required when such an integration is created, rejected for other types. Provide alongside client_secret to rotate client.
clientSecretstring
The secret issued for client_id. Required when an integration that authenticates with OAuth client credentials is created, and never returned by the API. Provide alongside client_id to rotate client.
connectorstringread-only
The user who last connected new credentials for the integration, at credential_update_time. Unset if they were connected by something other than a user, such as a service account.

Format: users/{user}
installLinkValuestring
The ID of an install link, the last segment of its name, which lets a user who isn’t an admin create an integration of the link’s kind. The link can only be used once.
One of
- oktaOkta
  clientIdstringrequired
  The client ID issued when the Oblique app is installed from the Okta Integration Network catalog, which Oblique authenticates to Okta as. Required when the integration is created, together with client_secret.
  clientSecretstringrequired
  The client secret issued alongside client_id when the Oblique app is installed. Required when the integration is created, and never returned by the API; provide it again to rotate.
  domainBaseUristringrequired
  Full base URL of the Okta domain, including the schema. For example: https://dev-45752433-admin.okta.com
  displayNamestring
  Will be removed in the future in favor of top level display_name.
  organizationIdstringread-only
  The tenant ID of the Okta organization. This is detected on first creation of the integration and is not editable.
  manageResourcesbooleanread-only
  Whether Oblique manages the org’s groups and applications, creating groups and changing membership and assignments, which a resource in push mode needs. False when the connection is read-only, either because read_only holds Oblique to reading or because the Oblique app in Okta wasn’t granted the scopes to manage them. Either way the connection imports users, groups, applications, and their memberships, and writes nothing back to Okta.
  readOnlyboolean
  Set once, when the resource is created. Whether Oblique asks Okta only for the access to read the org. The Oblique app is installed with the scopes to manage groups and applications, so this keeps a connection read-only without editing the app’s grants in Okta. Set when the integration is created and not editable afterwards: create the integration again to change it.
  
  Oblique won’t write to Okta while this is set, but it is Oblique’s own setting rather than a limit Okta enforces: the app keeps the scopes it was installed with.
  
  A connection that leaves this unset can still be read-only, when the Oblique app wasn’t granted those scopes. Either way, manage_resources reports whether the connection writes to Okta.
- googleGoogle
  domainstringrequired
  The domain to query for groups and memberships.
  missingReportsScopesbooleanread-only
  Whether the connection is missing the Google OAuth scopes required to sync sign-in reports from the Google Workspace audit logs.
  connectedAccountEmailstringread-only
  The email of the Workspace administrator who authorized the connection.
- slackSlack
  teamIdstringrequired
  The team ID that has been configured for notifications.
  teamNamestringread-only
  The human readable name of the team that has been configured for notifications.
  channelIdsstring[]
  Channels to send notifications to.
  dmDisabledboolean
  Whether DM notifications are disabled. This is false by default.
  domainBaseUristringread-only
  The domain base URI of the Slack instance, including the schema. This is detected on creation and is not editable. For example: https://myworkspace.slack.com
  allowApprovalWorkflowboolean
  Whether reviewers can approve requests directly from the Slack notification. This is true by default.
- githubGitHub
  orgstringrequired
  The GitHub organization name to sync members and teams from. May be changed by the user on the GitHub side.
  orgIdstringread-only
  The immutable GitHub organization ID.
  installationIdstringread-only
  The GitHub App installation ID for this organization. Set by the installation callback.
  readOnlyboolean
  Whether Oblique asks GitHub only for the access to read the organization. The Oblique GitHub App is installed with the permissions to manage organization membership, teams and repository access, so this keeps a connection read-only without changing the app.
  
  GitHub enforces it: every access token Oblique uses for the organization holds the app’s permissions at read access only. The app itself keeps the permissions it was installed with.
  
  A read-only integration can be made read-write by clearing this, which takes effect from the next sync. A read-write integration can’t be made read-only: remove the integration and connect it again instead.
- cloudflareCloudflare
  accountIdstringread-only
  The ID of the Cloudflare account that members and policies are synced from. Determined by the account the admin grants access to when connecting, and not editable afterwards.
  accountNamestringread-only
  The human readable name of the Cloudflare account, read from Cloudflare when the integration is connected. Empty if Cloudflare reports the account without a name.
- notionNotion
  workspaceIdstringread-only
  The ID of the Notion workspace that members are synced from. Determined by the workspace the admin grants access to when connecting, and not editable afterwards.
  workspaceNamestringread-only
  The human readable name of the Notion workspace, read from Notion when the integration is connected. Empty if Notion reports the workspace without a name.
- linearLinear
  workspaceIdstringread-only
  The ID of the Linear workspace that members and teams are synced from. Determined by the workspace the admin grants access to when connecting, and not editable afterwards.
  workspaceNamestringread-only
  The human readable name of the Linear workspace, read from Linear when the integration is connected.
  uriKeystringread-only
  The URL key of the Linear workspace, used to build links into Linear. For example oblique for https://linear.app/oblique.
- claudeConsoleClaudeConsole
  apiKeystringrequired
  The admin API key used to read the organization’s members and workspaces. Required when the integration is created, and never returned by the API. Provide it again to rotate the key.
  organizationIdstringread-only
  The ID of the Anthropic organization that members and workspaces are synced from. Determined by the organization the API key belongs to, and not editable afterwards.
  organizationNamestringread-only
  The human readable name of the Anthropic organization, read from Anthropic when the integration is connected.
- posthogPostHog
  organizationIdstringread-only
  The ID of the PostHog organization that members and projects are synced from. Determined by the organization the admin grants access to when connecting, and not editable afterwards.
  organizationNamestringread-only
  The human readable name of the PostHog organization, read from PostHog when the integration is connected.
  baseUristringread-only
  The base URI of the PostHog region the organization lives in. Either https://us.posthog.com or https://eu.posthog.com.
- bamboohrBambooHR
  subdomainstringread-only
  The subdomain of the BambooHR account that employees are synced from: “acme” for an account reached at https://acme.bamboohr.com. BambooHR serves each account’s authorization endpoints from its own subdomain, so this is provided by the admin when connecting and is not editable afterwards.
- rampRamp
  businessIdstringread-only
  The ID of the Ramp business that users are synced from. Determined by the business the admin grants access to when connecting, and not editable afterwards.
  businessNamestringread-only
  The legal name of the Ramp business, read from Ramp when the integration is connected. Empty if Ramp reports the business without one.
- tailscaleTailscale
  tailnetIdstringread-only
  The tailnet that users are synced from, as Tailscale reports it on the tailnet’s users, such as 5139383669875648. Determined by the default tailnet of the OAuth client’s tokens when the integration is connected, and not editable afterwards.
  tailnetNamestringread-only
  The human readable name of the tailnet, read from Tailscale when the integration is connected: the name of the organization’s earliest created tailnet. Empty when the OAuth client lacks the tailnets:read scope.
- onepasswordOnePassword
  accountIdstringrequired
  Set once, when the resource is created. The 1Password account that users are synced from, such as ABYALEX3KZF3ZD4DJVBKARRNPY. 1Password reports no account for an OAuth client, so this is provided by the admin when connecting: it’s the string between /app#/ and /AllItems in the address of the account’s vault items page.
  domainstringrequired
  Set once, when the resource is created. The domain of the account’s sign-in address, such as acme.1password.com, provided by the admin when connecting. The domain it’s under, one of 1password.com, 1password.ca, 1password.eu, or ent.1password.com, decides the region whose API the integration reads.
- gongGong
  baseUristringread-only
  The API base URL Gong serves the company’s data from, such as https://company-17.api.gong.io. Gong reports it when the admin connects, since every company is served from a host of its own, and it is not editable afterwards.
userCountinteger (int32)read-only
The number of users that the system contains.
resourceCountinteger (int32)read-only
The number of resources that the system manages.
accountCountinteger (int32)read-only
The number of accounts the integration reports, deactivated accounts included. Matches what ListIntegrationAccounts returns for it.
attributeCountinteger (int32)read-only
The number of user attributes the integration syncs.
resourcePushCountinteger (int32)read-only
The number of resources that have been pushed to the integration.
resourcePullCountinteger (int32)read-only
The number of resources that have been pulled from the integration.
supportsPushbooleanread-only
Whether the integration can push to at least one of the objects it reports. Some of its write capabilities may still be unavailable. Determined by the access the integration was granted, and re-evaluated on every sync.
syncsUserAttributesbooleanread-only
Whether the integration is a source of directory users and the attributes held against them. Only such an integration may be named the source of a core attribute. Reported by the integration’s syncer, so it is unset until the integration has synced once.
syncsUserPicturesbooleanread-only
Whether the integration reports users’ profile photos. Only such an integration may be named the source of profile photos. Reported by the integration’s syncer, so it is unset until the integration has synced once.
needsReauthbooleanread-only
Whether the integration is missing access that Oblique asks for, which is granted by reconnecting it. Re-evaluated on every sync.
nextSyncTimestring (date-time)read-only
When Oblique expects to sync the integration again, recorded at the end of every sync. An integration is synced again once its interval has passed, the part of the request budget its last sync spent has come back, and any rate limit that sync hit has reset, so a large organization or a busy API pushes this further out.

Unset until the integration has synced once, and for the integrations whose syncers don’t report a schedule.

Response

200Integration

Integrations connect Oblique with external systems in your organization. Oblique can both pull information from and push access decisions back to integrations.

namestring
Assigned by Oblique. Name of the integration of the format integrations/{integration}.
managementManagement
How this integration is managed. Set automatically by the server based on the calling client. Omitted from responses when the integration is manually managed (the default).
- managerstring
  Allowed values: TERRAFORM
  How the API object is managed. Set automatically by the server based on the caller: Terraform clients produce TERRAFORM; for all other clients the management field is left unset on the response.
- repoUristring
  URI of the VCS repository that holds the Terraform configuration for this API object. Populated by the Oblique Terraform provider.
- repoDirstring
  Optionally, the subdirectory within repo_uri that holds the Terraform configuration for this API object. Populated by the Oblique Terraform provider.
displayNamestring
A human readable name of the integration. For example “Okta Test”.
createTimestring (date-time)read-only
Create and update timestamps.
updateTimestring (date-time)read-only
deleteTimestring (date-time)read-only
The time when the integration was deleted.
credentialUpdateTimestring (date-time)read-only
The time a person last connected new credentials for the integration, for example by adding it, reauthorizing it, or reinstalling its app. Automatic token refreshes don’t change it.
clientIdstring
The ID of the OAuth client the integration authenticates with for integrations like Tailscale and 1Password. Required when such an integration is created, rejected for other types. Provide alongside client_secret to rotate client.
clientSecretstring
The secret issued for client_id. Required when an integration that authenticates with OAuth client credentials is created, and never returned by the API. Provide alongside client_id to rotate client.
connectorstringread-only
The user who last connected new credentials for the integration, at credential_update_time. Unset if they were connected by something other than a user, such as a service account.

Format: users/{user}
installLinkValuestring
The ID of an install link, the last segment of its name, which lets a user who isn’t an admin create an integration of the link’s kind. The link can only be used once.
One of
- oktaOkta
  clientIdstringrequired
  The client ID issued when the Oblique app is installed from the Okta Integration Network catalog, which Oblique authenticates to Okta as. Required when the integration is created, together with client_secret.
  clientSecretstringrequired
  The client secret issued alongside client_id when the Oblique app is installed. Required when the integration is created, and never returned by the API; provide it again to rotate.
  domainBaseUristringrequired
  Full base URL of the Okta domain, including the schema. For example: https://dev-45752433-admin.okta.com
  displayNamestring
  Will be removed in the future in favor of top level display_name.
  organizationIdstringread-only
  The tenant ID of the Okta organization. This is detected on first creation of the integration and is not editable.
  manageResourcesbooleanread-only
  Whether Oblique manages the org’s groups and applications, creating groups and changing membership and assignments, which a resource in push mode needs. False when the connection is read-only, either because read_only holds Oblique to reading or because the Oblique app in Okta wasn’t granted the scopes to manage them. Either way the connection imports users, groups, applications, and their memberships, and writes nothing back to Okta.
  readOnlyboolean
  Set once, when the resource is created. Whether Oblique asks Okta only for the access to read the org. The Oblique app is installed with the scopes to manage groups and applications, so this keeps a connection read-only without editing the app’s grants in Okta. Set when the integration is created and not editable afterwards: create the integration again to change it.
  
  Oblique won’t write to Okta while this is set, but it is Oblique’s own setting rather than a limit Okta enforces: the app keeps the scopes it was installed with.
  
  A connection that leaves this unset can still be read-only, when the Oblique app wasn’t granted those scopes. Either way, manage_resources reports whether the connection writes to Okta.
- googleGoogle
  domainstringrequired
  The domain to query for groups and memberships.
  missingReportsScopesbooleanread-only
  Whether the connection is missing the Google OAuth scopes required to sync sign-in reports from the Google Workspace audit logs.
  connectedAccountEmailstringread-only
  The email of the Workspace administrator who authorized the connection.
- slackSlack
  teamIdstringrequired
  The team ID that has been configured for notifications.
  teamNamestringread-only
  The human readable name of the team that has been configured for notifications.
  channelIdsstring[]
  Channels to send notifications to.
  dmDisabledboolean
  Whether DM notifications are disabled. This is false by default.
  domainBaseUristringread-only
  The domain base URI of the Slack instance, including the schema. This is detected on creation and is not editable. For example: https://myworkspace.slack.com
  allowApprovalWorkflowboolean
  Whether reviewers can approve requests directly from the Slack notification. This is true by default.
- githubGitHub
  orgstringrequired
  The GitHub organization name to sync members and teams from. May be changed by the user on the GitHub side.
  orgIdstringread-only
  The immutable GitHub organization ID.
  installationIdstringread-only
  The GitHub App installation ID for this organization. Set by the installation callback.
  readOnlyboolean
  Whether Oblique asks GitHub only for the access to read the organization. The Oblique GitHub App is installed with the permissions to manage organization membership, teams and repository access, so this keeps a connection read-only without changing the app.
  
  GitHub enforces it: every access token Oblique uses for the organization holds the app’s permissions at read access only. The app itself keeps the permissions it was installed with.
  
  A read-only integration can be made read-write by clearing this, which takes effect from the next sync. A read-write integration can’t be made read-only: remove the integration and connect it again instead.
- cloudflareCloudflare
  accountIdstringread-only
  The ID of the Cloudflare account that members and policies are synced from. Determined by the account the admin grants access to when connecting, and not editable afterwards.
  accountNamestringread-only
  The human readable name of the Cloudflare account, read from Cloudflare when the integration is connected. Empty if Cloudflare reports the account without a name.
- notionNotion
  workspaceIdstringread-only
  The ID of the Notion workspace that members are synced from. Determined by the workspace the admin grants access to when connecting, and not editable afterwards.
  workspaceNamestringread-only
  The human readable name of the Notion workspace, read from Notion when the integration is connected. Empty if Notion reports the workspace without a name.
- linearLinear
  workspaceIdstringread-only
  The ID of the Linear workspace that members and teams are synced from. Determined by the workspace the admin grants access to when connecting, and not editable afterwards.
  workspaceNamestringread-only
  The human readable name of the Linear workspace, read from Linear when the integration is connected.
  uriKeystringread-only
  The URL key of the Linear workspace, used to build links into Linear. For example oblique for https://linear.app/oblique.
- claudeConsoleClaudeConsole
  apiKeystringrequired
  The admin API key used to read the organization’s members and workspaces. Required when the integration is created, and never returned by the API. Provide it again to rotate the key.
  organizationIdstringread-only
  The ID of the Anthropic organization that members and workspaces are synced from. Determined by the organization the API key belongs to, and not editable afterwards.
  organizationNamestringread-only
  The human readable name of the Anthropic organization, read from Anthropic when the integration is connected.
- posthogPostHog
  organizationIdstringread-only
  The ID of the PostHog organization that members and projects are synced from. Determined by the organization the admin grants access to when connecting, and not editable afterwards.
  organizationNamestringread-only
  The human readable name of the PostHog organization, read from PostHog when the integration is connected.
  baseUristringread-only
  The base URI of the PostHog region the organization lives in. Either https://us.posthog.com or https://eu.posthog.com.
- bamboohrBambooHR
  subdomainstringread-only
  The subdomain of the BambooHR account that employees are synced from: “acme” for an account reached at https://acme.bamboohr.com. BambooHR serves each account’s authorization endpoints from its own subdomain, so this is provided by the admin when connecting and is not editable afterwards.
- rampRamp
  businessIdstringread-only
  The ID of the Ramp business that users are synced from. Determined by the business the admin grants access to when connecting, and not editable afterwards.
  businessNamestringread-only
  The legal name of the Ramp business, read from Ramp when the integration is connected. Empty if Ramp reports the business without one.
- tailscaleTailscale
  tailnetIdstringread-only
  The tailnet that users are synced from, as Tailscale reports it on the tailnet’s users, such as 5139383669875648. Determined by the default tailnet of the OAuth client’s tokens when the integration is connected, and not editable afterwards.
  tailnetNamestringread-only
  The human readable name of the tailnet, read from Tailscale when the integration is connected: the name of the organization’s earliest created tailnet. Empty when the OAuth client lacks the tailnets:read scope.
- onepasswordOnePassword
  accountIdstringrequired
  Set once, when the resource is created. The 1Password account that users are synced from, such as ABYALEX3KZF3ZD4DJVBKARRNPY. 1Password reports no account for an OAuth client, so this is provided by the admin when connecting: it’s the string between /app#/ and /AllItems in the address of the account’s vault items page.
  domainstringrequired
  Set once, when the resource is created. The domain of the account’s sign-in address, such as acme.1password.com, provided by the admin when connecting. The domain it’s under, one of 1password.com, 1password.ca, 1password.eu, or ent.1password.com, decides the region whose API the integration reads.
- gongGong
  baseUristringread-only
  The API base URL Gong serves the company’s data from, such as https://company-17.api.gong.io. Gong reports it when the admin connects, since every company is served from a host of its own, and it is not editable afterwards.
userCountinteger (int32)read-only
The number of users that the system contains.
resourceCountinteger (int32)read-only
The number of resources that the system manages.
accountCountinteger (int32)read-only
The number of accounts the integration reports, deactivated accounts included. Matches what ListIntegrationAccounts returns for it.
attributeCountinteger (int32)read-only
The number of user attributes the integration syncs.
resourcePushCountinteger (int32)read-only
The number of resources that have been pushed to the integration.
resourcePullCountinteger (int32)read-only
The number of resources that have been pulled from the integration.
supportsPushbooleanread-only
Whether the integration can push to at least one of the objects it reports. Some of its write capabilities may still be unavailable. Determined by the access the integration was granted, and re-evaluated on every sync.
syncsUserAttributesbooleanread-only
Whether the integration is a source of directory users and the attributes held against them. Only such an integration may be named the source of a core attribute. Reported by the integration’s syncer, so it is unset until the integration has synced once.
syncsUserPicturesbooleanread-only
Whether the integration reports users’ profile photos. Only such an integration may be named the source of profile photos. Reported by the integration’s syncer, so it is unset until the integration has synced once.
needsReauthbooleanread-only
Whether the integration is missing access that Oblique asks for, which is granted by reconnecting it. Re-evaluated on every sync.
nextSyncTimestring (date-time)read-only
When Oblique expects to sync the integration again, recorded at the end of every sync. An integration is synced again once its interval has passed, the part of the request budget its last sync spent has come back, and any rate limit that sync hit has reset, so a large organization or a busy API pushes this further out.

Unset until the integration has synced once, and for the integrations whose syncers don’t report a schedule.

Errors

Status	Meaning
`400`	Malformed request
`401`	Missing or invalid API key
`403`	Not allowed for this API key
`404`	Not found
`429`	Too many requests
`500`	Internal server error