Initiate Client ID Request

Queues a client ID authorization request for a domain. The domain must exist in the workspace and have an admin mailbox.

The platform is taken from that admin mailbox, and the two platforms authorize an app differently:

GOOGLE - the client ID is marked as a trusted app in Google Admin. Set delegated to true to register it under domain-wide delegation with explicit OAuth scopes, which must be full https:// Google scope URLs.

MICROSOFT / AZURE - the app is granted tenant-wide admin consent. client_id must be a GUID (an Entra application id), scopes are always applied, and delegated is rejected because there is only one grant mechanism. Scopes are permission names (Mail.Send) or resource-qualified (https://outlook.office365.com/SMTP.Send).

Delegated scopes vs application permissions

Microsoft has two kinds of permission, and they are not interchangeable:

scopes grants delegated permissions, which apply when a signed-in user acts through the app.

app_roles grants application permissions, which apply when the app acts as itself using a client-credentials (app-only) token.

If your integration authenticates as the application rather than as a user, you need app_roles. A token issued through the client-credentials flow carries only application permissions, so an app that was granted delegated scopes alone has an empty roles claim and its calls are refused with ErrorAccessDenied.

Send both when the same permission is used from both flows:

{
  "domain": "example.com",
  "client_id": "11111111-2222-3333-4444-555555555555",
  "scopes": ["Mail.Send"],
  "app_roles": ["Mail.Send"]
}

app_roles is rejected for GOOGLE domains, which have no equivalent - domain-wide delegation grants delegated scopes only.

Microsoft grants are asynchronous - they need a tenant admin sign-in - so the request stays processing for minutes and completes once the grant has been applied. Poll the status endpoint rather than assuming a fast result. While it is waiting the status endpoint reports processing, never errored.

A domain may hold admin mailboxes on more than one platform; pass platform to be explicit in that case.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location 'https://api.inboxkit.com/v1/api/mailboxes/client-id-request/initiate' \ --header 'X-Workspace-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "domain": "example.com", "client_id": "123456789-abcdefghijklmnop.apps.googleusercontent.com", "platform": "GOOGLE", "delegated": false, "scopes": [ "Mail.Send", "Mail.ReadWrite" ], "app_roles": [ "Mail.Send" ], "request_data": {} }'

{ "error": false, "message": "Client ID request initiated successfully", "data": { "uid": "req-a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "queued", "domain_name": "example.com", "client_id": "123456789-abcdefghijklmnop.apps.googleusercontent.com", "platform": "GOOGLE", "delegated": true, "scopes": [ "https://www.googleapis.com/auth/gmail.modify", "https://www.googleapis.com/auth/admin.directory.user" ], "app_roles": [ "Mail.Send" ], "created_at": "2025-01-15T10:00:00.000Z" } }

Initiate Client ID Request

Delegated scopes vs application permissions#

Request

Responses

Delegated scopes vs application permissions