Organization connections

9 operations

List organization connections

get/v1/org-connections

SDK workwae.orgConnections.list()

Errors

It answers only the errors every operation can answer. Each error's reason is the body's code.

Responses

200OK
application/json
OrgConnectionList
- itemsarray of OrgConnection
  Item properties
  idstring (uuid)
  kindenum
  One of"google_delegation""microsoft_app"
  namestring
  clientIdstring
  statusenum
  One of"pending_consent""unverified""active""failing"
  statusDetailstring or null
  checkedAtstring (date-time) or null
  googleGoogleDelegation or null
  Properties
  domainstring
  serviceAccountEmailstring
  directoryAdminstring or null
  scopesarray of string
  microsoftMicrosoftAppAccess or null
  Properties
  cloudenum
  One of"global""gcc-high""dod""china"
  credentialTypeenum
  One of"platform""client_secret""certificate"
  directoryIdstring or null
  permissionsarray of GraphPermission
  Item properties
  namestring
  isRequiredboolean
  accountsinteger
  createdAtstring (date-time)
  updatedAtstring (date-time)
Headers
- X-Request-IdstringThe request's id: the X-Request-Id you sent when it is 1 to 128 of A-Z a-z 0-9 . _ : -, else one the API generated.
- RateLimit-LimitintegerRequests the tightest of the plan's per-minute windows (tenant, credential) admits.
- RateLimit-RemainingintegerRequests that window still admits.
- RateLimit-ResetintegerSeconds until that window ends.

curl

SDK

curl -X GET "https://api.workwae.com/v1/org-connections" \
  -H "Authorization: Bearer $WORKWAE_API_KEY"

Register an organization connection

post/v1/org-connections

SDK workwae.orgConnections.create()

Google: the service account key is checked and sealed; authorize the returned clientId for the returned scopes in the Admin console, then test. Microsoft: a platform connection starts in pending_consent (POST .../consent); a tenant app with a directoryId starts unverified.

Errors

Status	Reason	When
400	invalid_service_account_key	serviceAccountKey is not a usable Google service account key.
400	invalid_certificate	The certificate or private key is not a usable PEM certificate and unencrypted PKCS#8 RSA key.
400	directory_id_not_allowed	A directoryId is given for a platform connection.
400	provider_not_configured	A platform connection names a cloud the platform has no app for.

It can also answer the errors every operation can answer. Each error's reason is the body's code.

Parameters

Name	In	Schema
Idempotency-Key	header	Makes the request safe to retry: the first answer to the key is kept for 24 hours and answered again to the same request. string length 1 to 255

Request body

required

application/json

one of

Option 1object
- kindconstantrequired
  Value"google_delegation"
- namestringrequired
  length 1 to 100
- serviceAccountKeystringrequired
  length 2 to 20000
- domainstringrequired
  length 3 to 253
- calendarEnabledboolean
  Default true
- contactsEnabledboolean
  Default false
- directoryAdminstring (email)
  max length 320
Option 2object
- kindconstantrequired
  Value"microsoft_app"
- namestringrequired
  length 1 to 100
- cloudenum
  One of"global""gcc-high""dod""china"Default "global"
- credentialone ofrequired
  One of
  1. Option 1object
    typeconstantrequired
    Value"platform"
  2. Option 2object
    typeconstantrequired
    Value"client_secret"
    clientIdstringrequired
    length 1 to 100
    clientSecretstringrequired
    length 1 to 1024
  3. Option 3object
    typeconstantrequired
    Value"certificate"
    clientIdstringrequired
    length 1 to 100
    certificatestringrequired
    length 1 to 20000
    privateKeystringrequired
    length 1 to 20000
- directoryIdstring
  length 1 to 100

Responses

201OK
application/json
OrgConnection
- idstring (uuid)
- kindenum
  One of"google_delegation""microsoft_app"
- namestring
- clientIdstring
- statusenum
  One of"pending_consent""unverified""active""failing"
- statusDetailstring or null
- checkedAtstring (date-time) or null
- googleGoogleDelegation or null
  Properties
  domainstring
  serviceAccountEmailstring
  directoryAdminstring or null
  scopesarray of string
- microsoftMicrosoftAppAccess or null
  Properties
  cloudenum
  One of"global""gcc-high""dod""china"
  credentialTypeenum
  One of"platform""client_secret""certificate"
  directoryIdstring or null
  permissionsarray of GraphPermission
  Item properties
  namestring
  isRequiredboolean
- accountsinteger
- createdAtstring (date-time)
- updatedAtstring (date-time)
Headers
- X-Request-IdstringThe request's id: the X-Request-Id you sent when it is 1 to 128 of A-Z a-z 0-9 . _ : -, else one the API generated.
- RateLimit-LimitintegerRequests the tightest of the plan's per-minute windows (tenant, credential) admits.
- RateLimit-RemainingintegerRequests that window still admits.
- RateLimit-ResetintegerSeconds until that window ends.
- Idempotent-Replayedconstanttrue when this is the kept answer to an earlier request with the same Idempotency-Key.

curl

SDK

curl -X POST "https://api.workwae.com/v1/org-connections" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "kind": "google_delegation",
  "name": "string",
  "serviceAccountKey": "string",
  "domain": "string"
}'

Get an organization connection

get/v1/org-connections/{connectionId}

SDK workwae.orgConnections.get()

Errors

Status	Reason	When
404	org_connection_not_found	The organization connection does not exist.

It can also answer the errors every operation can answer. Each error's reason is the body's code.

Parameters

Name	In	Schema
connectionIdrequired	path	string (uuid)

Responses

200OK
application/json
OrgConnection
- idstring (uuid)
- kindenum
  One of"google_delegation""microsoft_app"
- namestring
- clientIdstring
- statusenum
  One of"pending_consent""unverified""active""failing"
- statusDetailstring or null
- checkedAtstring (date-time) or null
- googleGoogleDelegation or null
  Properties
  domainstring
  serviceAccountEmailstring
  directoryAdminstring or null
  scopesarray of string
- microsoftMicrosoftAppAccess or null
  Properties
  cloudenum
  One of"global""gcc-high""dod""china"
  credentialTypeenum
  One of"platform""client_secret""certificate"
  directoryIdstring or null
  permissionsarray of GraphPermission
  Item properties
  namestring
  isRequiredboolean
- accountsinteger
- createdAtstring (date-time)
- updatedAtstring (date-time)
Headers
- X-Request-IdstringThe request's id: the X-Request-Id you sent when it is 1 to 128 of A-Z a-z 0-9 . _ : -, else one the API generated.
- RateLimit-LimitintegerRequests the tightest of the plan's per-minute windows (tenant, credential) admits.
- RateLimit-RemainingintegerRequests that window still admits.
- RateLimit-ResetintegerSeconds until that window ends.

curl

SDK

curl -X GET "https://api.workwae.com/v1/org-connections/6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b" \
  -H "Authorization: Bearer $WORKWAE_API_KEY"

Delete an organization connection

delete/v1/org-connections/{connectionId}

SDK workwae.orgConnections.delete()

Errors

Status	Reason	When
404	org_connection_not_found	The organization connection does not exist.
409	connection_in_use	Live accounts still authenticate through the connection.

It can also answer the errors every operation can answer. Each error's reason is the body's code.

Parameters

Name	In	Schema
connectionIdrequired	path	string (uuid)

Responses

204OK
No body.
Headers
- X-Request-IdstringThe request's id: the X-Request-Id you sent when it is 1 to 128 of A-Z a-z 0-9 . _ : -, else one the API generated.
- RateLimit-LimitintegerRequests the tightest of the plan's per-minute windows (tenant, credential) admits.
- RateLimit-RemainingintegerRequests that window still admits.
- RateLimit-ResetintegerSeconds until that window ends.

curl

SDK

curl -X DELETE "https://api.workwae.com/v1/org-connections/6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b" \
  -H "Authorization: Bearer $WORKWAE_API_KEY"

Update an organization connection

patch/v1/org-connections/{connectionId}

SDK workwae.orgConnections.update()

Replacing a credential or the authorized scopes makes the connection unverified until the next test.

Errors

Status	Reason	When
400	invalid_service_account_key	serviceAccountKey is not a usable Google service account key.
400	invalid_certificate	The certificate or private key is not a usable PEM certificate and unencrypted PKCS#8 RSA key.
400	directory_id_not_allowed	A directoryId is given for a platform connection.
400	credential_mismatch	A field does not apply to this connection's kind or credential type, or a certificate is replaced without its private key.
404	org_connection_not_found	The organization connection does not exist.

It can also answer the errors every operation can answer. Each error's reason is the body's code.

Parameters

Name	In	Schema
connectionIdrequired	path	string (uuid)

Request body

application/json

object

namestring
length 1 to 100
serviceAccountKeystring
length 2 to 20000
calendarEnabledboolean
contactsEnabledboolean
directoryAdminstring (email) or null
max length 320
clientSecretstring
length 1 to 1024
certificatestring
length 1 to 20000
privateKeystring
length 1 to 20000
directoryIdstring
length 1 to 100

Responses

200OK
application/json
OrgConnection
- idstring (uuid)
- kindenum
  One of"google_delegation""microsoft_app"
- namestring
- clientIdstring
- statusenum
  One of"pending_consent""unverified""active""failing"
- statusDetailstring or null
- checkedAtstring (date-time) or null
- googleGoogleDelegation or null
  Properties
  domainstring
  serviceAccountEmailstring
  directoryAdminstring or null
  scopesarray of string
- microsoftMicrosoftAppAccess or null
  Properties
  cloudenum
  One of"global""gcc-high""dod""china"
  credentialTypeenum
  One of"platform""client_secret""certificate"
  directoryIdstring or null
  permissionsarray of GraphPermission
  Item properties
  namestring
  isRequiredboolean
- accountsinteger
- createdAtstring (date-time)
- updatedAtstring (date-time)
Headers
- X-Request-IdstringThe request's id: the X-Request-Id you sent when it is 1 to 128 of A-Z a-z 0-9 . _ : -, else one the API generated.
- RateLimit-LimitintegerRequests the tightest of the plan's per-minute windows (tenant, credential) admits.
- RateLimit-RemainingintegerRequests that window still admits.
- RateLimit-ResetintegerSeconds until that window ends.

curl

SDK

curl -X PATCH "https://api.workwae.com/v1/org-connections/6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "name": "string"
}'

Start Microsoft admin consent

post/v1/org-connections/{connectionId}/consent

SDK workwae.orgConnections.consent()

Returns the URL an administrator of the directory grants consent at. Afterwards the browser returns to redirectUri with status=success|error, connection_id, error and state; the connection records the consenting directory and is tested. A tenant app uses /adminconsent. The platform app is consented through a sign-in (authorize with prompt=admin_consent) and records the directory named by the sign-in's ID token; it can only be started from the board, and the board user who started it has to be signed in, in the browser that returns, for the directory to be recorded. Errors on return include access_denied, consent_failed, consent_unverified, directory_mismatch and directory_already_connected (another platform connection holds the directory).

Errors

Status	Reason	When
400	not_microsoft	The connection is a Google connection.
400	redirect_uri_not_allowed	redirectUri is neither on the tenant allowlist (settings.redirectUris) nor the board.
400	provider_not_configured	A platform connection's cloud has no platform app (the platform's configuration changed).
403	session_required	A platform connection's consent is started by a caller that is not a board session.
404	org_connection_not_found	The organization connection does not exist.

It can also answer the errors every operation can answer. Each error's reason is the body's code.

Parameters

Name	In	Schema
connectionIdrequired	path	string (uuid)
Idempotency-Key	header	Makes the request safe to retry: the first answer to the key is kept for 24 hours and answered again to the same request. string length 1 to 255

Request body

required

application/json

object

redirectUristring (uri)required
statestring
max length 1024

Responses

200OK
application/json
ConsentLink
- consentUrlstring (uri)
Headers
- X-Request-IdstringThe request's id: the X-Request-Id you sent when it is 1 to 128 of A-Z a-z 0-9 . _ : -, else one the API generated.
- RateLimit-LimitintegerRequests the tightest of the plan's per-minute windows (tenant, credential) admits.
- RateLimit-RemainingintegerRequests that window still admits.
- RateLimit-ResetintegerSeconds until that window ends.
- Idempotent-Replayedconstanttrue when this is the kept answer to an earlier request with the same Idempotency-Key.

curl

SDK

curl -X POST "https://api.workwae.com/v1/org-connections/6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b/consent" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "redirectUri": "https://example.com/callback"
}'

Test an organization connection

post/v1/org-connections/{connectionId}/test

SDK workwae.orgConnections.test()

Requests a token the way accounts will and reports each check; the connection becomes active or failing. A passing test returns accounts that were moved to reauth_required to active. Google impersonates user (default: the directory admin).

Errors

Status	Reason	When
400	user_required	A Google connection has neither a user nor a directory admin to test as.
404	org_connection_not_found	The organization connection does not exist.
409	consent_required	No Microsoft directory has consented to the app yet.

It can also answer the errors every operation can answer. Each error's reason is the body's code.

Parameters

Name	In	Schema
connectionIdrequired	path	string (uuid)
Idempotency-Key	header	Makes the request safe to retry: the first answer to the key is kept for 24 hours and answered again to the same request. string length 1 to 255

Request body

application/json

object

userstring (email)
max length 320

Responses

200OK
application/json
OrgConnectionTestResult
- connectionOrgConnection
  Properties
  idstring (uuid)
  kindenum
  One of"google_delegation""microsoft_app"
  namestring
  clientIdstring
  statusenum
  One of"pending_consent""unverified""active""failing"
  statusDetailstring or null
  checkedAtstring (date-time) or null
  googleGoogleDelegation or null
  Properties
  domainstring
  serviceAccountEmailstring
  directoryAdminstring or null
  scopesarray of string
  microsoftMicrosoftAppAccess or null
  Properties
  cloudenum
  One of"global""gcc-high""dod""china"
  credentialTypeenum
  One of"platform""client_secret""certificate"
  directoryIdstring or null
  permissionsarray of GraphPermission
  Item properties
  namestring
  isRequiredboolean
  accountsinteger
  createdAtstring (date-time)
  updatedAtstring (date-time)
- checksarray of OrgConnectionCheck
  Item properties
  namestring
  isOkboolean
  isRequiredboolean
  detailstring
Headers
- X-Request-IdstringThe request's id: the X-Request-Id you sent when it is 1 to 128 of A-Z a-z 0-9 . _ : -, else one the API generated.
- RateLimit-LimitintegerRequests the tightest of the plan's per-minute windows (tenant, credential) admits.
- RateLimit-RemainingintegerRequests that window still admits.
- RateLimit-ResetintegerSeconds until that window ends.
- Idempotent-Replayedconstanttrue when this is the kept answer to an earlier request with the same Idempotency-Key.

curl

SDK

curl -X POST "https://api.workwae.com/v1/org-connections/6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b/test" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "user": "[email protected]"
}'

List the directory's mailboxes

get/v1/org-connections/{connectionId}/directory-entries

SDK workwae.orgConnections.directoryEntries()

Microsoft: Graph /users (needs User.Read.All). Google: the Admin SDK users.list as the directory admin (needs admin.directory.user.readonly). query matches the start of names and addresses. A nextCursor is good for an hour, on this connection only.

Errors

Status	Reason	When
400	invalid_cursor	The cursor is not one this list issued.
400	provider_rejected	The provider rejected the listing (e.g. the query).
404	org_connection_not_found	The organization connection does not exist.
404	provider_not_found	The provider no longer has the directory.
409	consent_required	No Microsoft directory has consented to the app yet.
409	directory_unavailable	The connection may not list the directory: there is no directory admin, the permission or scope is not granted, or the connection cannot get a token (test it).
429	provider_throttled	The provider asked us to slow down (with Retry-After when it named a wait).
502	provider_unavailable	The provider could not be reached (with Retry-After when it named a wait).

It can also answer the errors every operation can answer. Each error's reason is the body's code.

Parameters

Name	In	Schema
connectionIdrequired	path	string (uuid)
cursor	query	string length 1 to 512
limit	query	integer Default `100`1 to 200
query	query	string max length 100

Responses

200OK
application/json
DirectoryEntryPage
- itemsarray of DirectoryEntry
  Item properties
  idstring
  length 1 to 1024
  emailstring
  displayNamestring or null
  accountIdstring (uuid) or null
- nextCursorstring or null
  length 1 to 512
Headers
- X-Request-IdstringThe request's id: the X-Request-Id you sent when it is 1 to 128 of A-Z a-z 0-9 . _ : -, else one the API generated.
- RateLimit-LimitintegerRequests the tightest of the plan's per-minute windows (tenant, credential) admits.
- RateLimit-RemainingintegerRequests that window still admits.
- RateLimit-ResetintegerSeconds until that window ends.

curl

SDK

SDK paginate

curl -X GET "https://api.workwae.com/v1/org-connections/6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b/directory-entries" \
  -H "Authorization: Bearer $WORKWAE_API_KEY"

Add mailboxes as accounts

post/v1/org-connections/{connectionId}/accounts

SDK workwae.orgConnections.addAccounts()

Each mailbox is checked through the connection before its account is created (Google: a delegated token for it; Microsoft: its inbox). items holds one result per mailbox, in request order. Per-mailbox failures are reported there with the reason the API would answer with, e.g. invalid_grant (no such user), consent_revoked (the scopes or permissions are not granted), provider_forbidden or provider_not_found (no mailbox access), plan_limit_accounts (the plan's account limit was reached part way through; the mailboxes before it are created).

Errors

Status	Reason	When
400	storage_unavailable	settings.bodyStorage is cache or full and no object store is configured.
402	billing_past_due	The tenant's payment is past due beyond the grace period (sends already queued or scheduled still go out).
403	plan_limit_storage	settings.bodyStorage is cache or full and the tenant's plan does not include body storage.
404	org_connection_not_found	The organization connection does not exist.
409	consent_required	No Microsoft directory has consented to the app yet.

It can also answer the errors every operation can answer. Each error's reason is the body's code.

Parameters

Name	In	Schema
connectionIdrequired	path	string (uuid)
Idempotency-Key	header	Makes the request safe to retry: the first answer to the key is kept for 24 hours and answered again to the same request. string length 1 to 255

Request body

required

application/json

object

mailboxesarray of AddMailboxInputrequired
1 to 100 items
Item properties
- emailstring (email)required
  max length 320
- displayNamestring
  max length 255
- externalRefstring
  max length 255
settingsSettingsOverride
Properties
- bodyStorageenum
  One of"none""cache""full"
- syncWindowDaysinteger or null
  greater than 0
- calendarEnabledboolean
- contactsEnabledboolean
- undoSendSecondsinteger
  0 to 60
- trackOpensboolean
- trackClicksboolean
- trackingHoneypotboolean

Responses

200OK
application/json
AddedMailboxList
- itemsarray of AddedMailbox
  Item properties
  emailstring
  statusenum
  One of"created""exists""failed"
  accountIdstring (uuid) or null
  errorAddedMailboxError or null
  Properties
  reasonstring
  messagestring
Headers
- X-Request-IdstringThe request's id: the X-Request-Id you sent when it is 1 to 128 of A-Z a-z 0-9 . _ : -, else one the API generated.
- RateLimit-LimitintegerRequests the tightest of the plan's per-minute windows (tenant, credential) admits.
- RateLimit-RemainingintegerRequests that window still admits.
- RateLimit-ResetintegerSeconds until that window ends.
- Idempotent-Replayedconstanttrue when this is the kept answer to an earlier request with the same Idempotency-Key.

curl

SDK

curl -X POST "https://api.workwae.com/v1/org-connections/6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b/accounts" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "mailboxes": [
    {
      "email": "[email protected]"
    }
  ]
}'