Skip to content

Name the tenant's operational contacts

Tell the platform operator whom to reach in your tenant: one contact for service and maintenance notices, and one for security incidents and notices.

Who can do it

A tenant administrator, from code. Replacing the contacts needs the permission admin.tenant.operational-contact.manage, which the tenant administrator role holds. Reading them needs admin.tenant.operational-contact.read, which the other built-in tenant roles hold too.

  • A support-access session reads the contacts as the tenant does, and cannot replace them on any deployment type.
  • A platform administrator does not replace them on the tenant directly; platform staff read them on the platform's own tenant read.

No console screen offers this task.

Before you start

  • There are two categories, at most one contact each:
    • OPERATIONS: service and maintenance notices;
    • SECURITY: security incidents and notices.
  • Each contact is a name, an email address and, optionally, a phone number. Prefer a team name and a team mailbox over a person's, so the contact survives staff changes.
  • The limits, counted in characters, not bytes:
    • the name is 1 to 128 characters, not blank, on one line;
    • the email address is well formed and at most 254 characters (RFC 5321);
    • the phone number, when given, is in E.164 form (ITU-T E.164): a plus sign and at most 15 digits.
  • The request replaces the whole stored set: a category you leave out loses its contact, and an empty list removes every contact.
  • A closed tenant keeps its contacts and accepts no replacement.

Steps

  1. Read the current contacts: GET /api/v3/admin/tenants/{tenantId}/operational-contacts. The answer always carries contacts, an empty list when none is designated.
  2. Send the whole set you want stored: PUT /api/v3/admin/tenants/{tenantId}/operational-contacts with a body such as

    {
      "contacts": [
        {"category": "OPERATIONS", "name": "Platform Operations",
         "email": "[email protected]", "phone": "+14155550100"},
        {"category": "SECURITY", "name": "Security Operations Center",
         "email": "[email protected]"}
      ]
    }
    
  3. To remove every contact, send {"contacts": []}.

What you see when it worked

The answer is 200 with the stored set, in category order, as the read returns it; a contact without a phone number carries no phone member. Each contact the replace creates, changes or removes is recorded in your tenant's audit trail with its value before and after, all under one correlation id. Sending the stored set again changes nothing and records nothing.

If it fails

What you see Cause What to do
400, the detail naming the member Two contacts of one category, more than two contacts, a category other than OPERATIONS or SECURITY, a blank or too long name, a malformed or too long email address, or a phone number outside E.164. Nothing is changed Correct the member named
403 You lack the permission to replace the contacts, you act in a support-access session (impersonation-operation-forbidden), or you are a platform administrator acting on the tenant directly Have a tenant administrator replace them from their own session
404 The tenant is closed or is not one you may address Check the tenant identifier
503 with Retry-After Another replacement of the contacts, or a change of the tenant itself, held the tenant longer than 5 seconds. Nothing was changed Retry after the time stated

Without the console

Surface How
Admin CLI None
Admin SDK None
API GET /api/v3/admin/tenants/{tenantId}/operational-contacts (operation getTenantOperationalContacts)
API PUT /api/v3/admin/tenants/{tenantId}/operational-contacts with contacts (operation replaceTenantOperationalContacts)