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
- Read the current contacts:
GET /api/v3/admin/tenants/{tenantId}/operational-contacts. The answer always carriescontacts, an empty list when none is designated. -
Send the whole set you want stored:
PUT /api/v3/admin/tenants/{tenantId}/operational-contactswith a body such as{ "contacts": [ {"category": "OPERATIONS", "name": "Platform Operations", "email": "[email protected]", "phone": "+14155550100"}, {"category": "SECURITY", "name": "Security Operations Center", "email": "[email protected]"} ] } -
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) |
Related
- Rename your tenant: change the name your users see.
- Operation Not Available While Impersonating
- Serialised Operation Timed Out