Register an application
Register the business system on whose behalf cryptographic work is done, with its owner and risk labels. The platform creates the application together with its Default Cryptographic Actor, which is what later authenticates and calls the platform.
Who can do it
A tenant administrator or a tenant key manager, and a platform super admin working in a tenant on a private-cloud or on-premise deployment. On a SaaS deployment a platform administrator cannot work in another tenant's data. The console offers New application to a person who holds the permission to create applications; without it the control is shown disabled with the reason. Edit application, Suspend, Reactivate and Disable permanently are offered to a person who holds the permission to update applications.
Before you start
- Choose a name that no live application of your tenant already uses. Names are compared without regard to the case of the letters A to Z.
- A RAPIDAPI tenant does not create applications: the platform creates them, and the console does not show the control.
Steps
- Open Applications from the tenant's navigation.
- Select New application. The Create Application wizard opens.
- In Identity, enter the Application Name (required), and optionally a Display Name and a Description. Select Next.
- In Business Info, optionally set the Environment, Business Unit, Cost Center, Owner Name, Owner Email, Technical Contact Name and Technical Contact Email. Select Next.
- In Risk & Compliance, optionally set the Data Classification, the Risk Level and the Regulatory Scope; select Add for each regulation. Select Next.
- Check the summary, then select Create Application.
The business and risk values are labels. They are shown on the application and in reports, and none of them changes what the application is allowed to do.
To change an application later, open it from Applications; the controls are at the foot of its panel:
- Select Edit application, change the names or the business information, and select Save changes. Only the fields you change are sent. An emptied field keeps its current value: an application field cannot be cleared.
- To stop an active application, select Suspend, then Suspend application. Its actors cannot authenticate until it is reactivated, and its pending approval requests are cancelled; its keys, actors and exchanges are kept.
- To let a suspended application work again, select Reactivate, then Reactivate application. Its actors authenticate again with their own credentials.
- To stop an active or suspended application for good, select Disable permanently. Type the application's name to confirm, then select Disable permanently again; no reason is asked. Its actors can no longer authenticate and its pending approval requests are cancelled.
Disabling is permanent: a disabled application can never be reactivated, so the console offers no status action on it. Its record stays, and its names and business information can still be edited. To stop an application for a time, suspend it instead. Register a new application if the system is still needed after it was disabled.
What you see when it worked
The wizard shows Application Created and states that a Default Cryptographic Actor was created with the application. Select Open Default Actor to generate credentials to go to that actor, or Close.
The application appears in Applications as active, and the counts above the list are read again. A status change shows Application suspended, Application reactivated or Application disabled, and the panel shows the new status. Its Default Actor has no credential yet: nothing can authenticate as it until a credential is issued or an external identity is bound to it.
If it fails
| What you see | Cause | What to do |
|---|---|---|
| The wizard returns to the first step with the name refused | A live application of the tenant already holds that name, compared case-insensitively | Choose another name. A deleted application does not keep its name. See Application Name Conflict |
| Next stays disabled on the first step | The name is empty, or a name, display name or description is too long | Enter a name and shorten the field the counter marks |
| An e-mail field shows "Enter a valid email address" | The owner or technical contact e-mail is not an address | Correct it, or leave it empty |
| The creation is refused for the platform tenant | Applications cannot be created in the platform tenant | Create the application in a regular tenant |
| An error stays on the review step | The service refused or failed the write; nothing was created | Retry. If it recurs, quote the request id shown to the platform operator |
| The edit's name field is refused | Another live application of the tenant holds that name | Choose another name. See Application Name Conflict |
| The application was not updated, with the server's reason | The change was refused or failed; nothing was changed | Correct what the reason names, or retry |
| The application's status was not changed, with the server's reason | The suspension, reactivation or disabling was refused or failed; nothing was changed | Correct what the reason names, or retry |
| The status change is refused as a terminal state | The application is disabled, which is permanent; nothing in the change was applied | Register a new application. See Terminal application state |
| An edit shows The application was not updated above Save changes, refused as a concurrent modification; a status change shows it under The application's status was not changed | Another write (an edit, a status change, a deletion, a tenant closure) changed the application after it was read; nothing was applied | Open the application again and retry. See Concurrent Modification |
| The application could not be read for editing | The current record could not be read before the edit opened | Close the panel, open the application again and retry |
Without the console
| Surface | How |
|---|---|
| API | POST /api/v3/admin/tenants/{tenantId}/applications (operation createApplication); a name held by another live application is refused 409 application-name-conflict |
| API | PATCH /api/v3/admin/tenants/{tenantId}/applications/{applicationId} (operation updateApplication): changes the names, labels or status of an application; the console's Edit application, Suspend, Reactivate and Disable permanently call it. Setting status to DISABLED disables it permanently: a later change to ACTIVE or SUSPENDED is refused 409 terminal-application-state and applies nothing, while a change that keeps DISABLED or omits status still edits the other fields. A new name held by another live application is refused 409 application-name-conflict, and a write that lost a race with another one 409 concurrent-modification |
Related
- Applications: what the screen shows and every decision you make on it.