Create application
The endpoint provides functionality to create an application.
The following application types are supported:
Using OAuth 2.0 / OIDC protocol
- Single-page application (
spa
) - Regular web application (
webOauth
) - Native application (
nat
) - Server-to-server application (
s2s
)
- Single-page application (
Using SAML 2.0 protocol
- Regular web application (
webSaml
)
- Regular web application (
HTTP request
POST https://$instanceId.id.nevis.cloud/nevis/api/v1/applications
Parameters
Parameter | In | Type | Required / Optional | Description |
---|---|---|---|---|
instanceId | path | string | required | The ID of your Identity Cloud instance |
Request body
An application can be created by providing the name
, type
, protocol
and the parameters specific to each type of application.
Parameter | Type | Required / Optional | Description |
---|---|---|---|
name | string | Required | The name of the application. Constraint: The name must be unique, contain only alphanumeric characters and underscores, and have a maximum length of 30 characters. |
type | string | Required | The type of the application; Values: spa , web , nat , s2s |
protocol | string | Required | The protocol of the application; Values: oauthOidc , saml |
spa | object | Required, if type is spa | The parameters of the spa application |
webOauth | object | Required, if type is web and protocol is oauthOidc | The parameters of the webOauth application |
nat | object | Required, if type is nat | The parameters of the nat application |
s2s | object | Required, if type is s2s | The parameters of the s2s application |
webSaml | object | Required, if type is web and protocol is saml | The parameters of the webSaml application |
Application object
spa
Parameter | Type | Required / Optional | Description |
---|---|---|---|
clientId | string | Optional | The unique public identifier of the application. If not provided in the request, a clientId is randomly generated. Constraint: The clientId must be unique, and have a minimum length of 16 characters, and a maximum length of 1024 characters. |
allowedReturnUris | string[] | Required | The user is redirected to the Return URI after successfully authorizing the application. This can be a classic URL, or a custom scheme URL that triggers a mobile application. Constraint: The allowedReturnUris may include several URIs, up to a maximum of 20 . A Return URI must have a maximum length of 2048 characters. |
accessTokenLifetime | string | Optional | Specifies the lifetime of the issued access tokens for the application. Constraint: The accessTokenLifetime must be in the range [1m , 1440m ]. Default: 60m |
idTokenLifetime | string | Optional | Specifies the lifetime of the issued ID tokens for the application. Constraint: The idTokenLifetime must be in the range [1m , 1440m ]. Default: 10m |
refreshTokenLifetime | string | Optional | Specifies the lifetime of the issued refresh tokens for the application. Constraint: The refreshTokenLifetime must be in the range [1d , 365d ]. Default: 30d |
webOauth
Parameter | Type | Required / Optional | Description |
---|---|---|---|
clientId | string | Optional | The unique public identifier of the application. If not provided in the request, a clientId is randomly generated. Constraint: The clientId must be unique, and have a minimum length of 16 characters, and a maximum length of 1024 characters. |
clientSecret | string | Optional | The private identifier of the application. The clientSecret is used by application with a server-side component. Known by the application and the authorization server only. If not provided in the request, a clientSecret is randomly generated. Constraint: The clientSecret must have a minimum length of 16 characters, and a maximum length of 1024 characters. |
allowedReturnUris | string[] | Required | The user is redirected to the Return URI after successfully authorizing the application. This can be a classic URL, or a custom scheme URL that triggers a mobile application. Constraint: The allowedReturnUris may include several URIs, up to a maximum of 20 . A Return URI must have a maximum length of 2048 characters. |
accessTokenLifetime | string | Optional | Specifies the lifetime of the issued access tokens for the application. Constraint: The accessTokenLifetime must be in the range [1m , 1440m ]. Default: 60m |
idTokenLifetime | string | Optional | Specifies the lifetime of the issued ID tokens for the application. Constraint: The idTokenLifetime must be in the range [1m , 1440m ]. Default: 10m |
refreshTokenLifetime | string | Optional | Specifies the lifetime of the issued refresh tokens for the application. Constraint: The refreshTokenLifetime must be in the range [1d , 365d ]. Default: 30d |
nat
Parameter | Type | Required / Optional | Description |
---|---|---|---|
clientId | string | Optional | The unique public identifier of the application. If not provided in the request, a clientId is randomly generated. Constraint: The clientId must be unique, and have a minimum length of 16 characters, and a maximum length of 1024 characters. |
allowedReturnUris | string[] | Required | The user is redirected to the Return URI after successfully authorizing the application. This can be a classic URL, or a custom scheme URL that triggers a mobile application. Constraint: The allowedReturnUris may include several URIs, up to a maximum of 20 . A Return URI must have a maximum length of 2048 characters. |
accessTokenLifetime | string | Optional | Specifies the lifetime of the issued access tokens for the application. Constraint: The accessTokenLifetime must be in the range [1m , 1440m ]. Default: 60m |
idTokenLifetime | string | Optional | Specifies the lifetime of the issued ID tokens for the application. Constraint: The idTokenLifetime must be in the range [1m , 1440m ]. Default: 10m |
refreshTokenLifetime | string | Optional | Specifies the lifetime of the issued refresh tokens for the application. Constraint: The refreshTokenLifetime must be in the range [1d , 365d ]. Default: 30d |
s2s
Parameter | Type | Required / Optional | Description |
---|---|---|---|
clientId | string | Optional | The unique public identifier of the application. If not provided in the request, a clientId is randomly generated. Constraint: The clientId must be unique, and have a minimum length of 16 characters, and a maximum length of 1024 characters. |
clientSecret | string | Optional | The private identifier of the application. The clientSecret is used by application with a server-side component. Known by the application and the authorization server only. If not provided in the request, a clientSecret is randomly generated. Constraint: The clientSecret must have a minimum length of 16 characters, and a maximum length of 1024 characters. |
accessTokenLifetime | string | Optional | Specifies the lifetime of the issued access tokens for the application. Constraint: The accessTokenLifetime must be in the range [1m , 1440m ]. Default: 60m |
webSaml
Parameter | Type | Required / Optional | Description |
---|---|---|---|
issuer | string | Required | Issuer is the unique identifier of the service provider (SP) application, typically in a URL format. The identifier is used by Identity Cloud (the IdP) to validate SAML messages (For example AuthnRequest) received from the SP. Constraint: The issuer must be unique, and have a maximum length of 1024 characters. Example: https://sp.your-company.com |
subject | string | Optional | The Subject contains an identifier of the user as known to Identity Cloud. This configuration determines whether the User ID or the Email address will be used as value of the NameID attribute in the SAML Assertion. Values: email , userId ; Default: email |
outboundBinding | string | Optional | The Outbound binding specifies how SAML messages are returned to the initiating application. Identity Cloud either instructs the user agent to send the message to the service provider using POST or returns a redirect (302 leading to a GET). Values: httpPost , httpRedirect ; Default: httpPost |
assertionConsumerServiceUrl | string | Required | Assertion Consumer Service URL indicates the URL, to which the SAML response is returned after successful authentication. Constraint: The assertionConsumerServiceUrl must have a maximum length of 1024 characters. Example: https://sp.your-company.com/login/saml2/sso/ |
audience | string | Optional | SP verifies if Audience matches the recipient of a SAML response. Audience has a URL format. Constraint: The audience must have a maximum length of 1024 characters. Example: https://sp.your-company.com |
x509SignerCertificate | string | Optional | X509 Signer Certificate is needed if your SP signs the AuthnRequest. Extract the public-key certificate from the configuration of the the SP, or the SAML metadata file of the SP. Constraint: The x509SignerCertificate has to be encoded in PEM format. Note: The x509SignerCertificate should includes \n for new lines, after -----BEGIN CERTIFICATE----- prefix and before -----END CERTIFICATE----- postfix. |
Example request
You need to provide the required name
, type
, protocol
and application type specific request body.
name=your_application
type=s2s
protocol=oauthOidc
curl --request POST "https://$instanceId.id.nevis.cloud/nevis/api/v1/applications" \
--header "Authorization: Bearer $accessKey" \
--header "Content-Type: application/json" \
--data "{ \"name\" : \"$name\", \"type\" : \"$type\", \"protocol\" : \"$protocol\", \"s2s\" : {} }"
Minimal spa
application request body
{
"name":"your_application",
"type":"spa",
"protocol":"oauthOidc",
"spa": {
"allowedReturnUris": [
"https://your-company.com/callback"
]
}
}
Minimal webOauth
application request body
{
"name":"your_application",
"type":"web",
"protocol":"oauthOidc",
"webOauth": {
"allowedReturnUris": [
"https://your-company.com/callback"
]
}
}
Minimal nat
application request body
{
"name":"your_application",
"type":"nat",
"protocol":"oauthOidc",
"nat": {
"allowedReturnUris": [
"https://your-company.com/callback"
]
}
}
Minimal s2s
application request body
{
"name":"your_application",
"type":"s2s",
"protocol":"oauthOidc",
"s2s": {}
}
Minimal webSaml
application request body
{
"name":"your_application",
"type":"web",
"protocol":"saml",
"webSaml": {
"issuer": "https://sp.your-company.com",
"assertionConsumerServiceUrl": "https://sp.your-company.com/login/saml2/sso/"
}
}
webSaml
application with X509 Signer Certificate request body
{
"name":"your_application",
"type":"web",
"protocol":"saml",
"webSaml": {
"issuer": "https://sp.your-company.com",
"assertionConsumerServiceUrl": "https://sp.your-company.com/login/saml2/sso/",
"x509SignerCertificate": "-----BEGIN CERTIFICATE-----\nyour-x509-signer-certificate\n-----END CERTIFICATE-----"
}
}
HTTP response
On success
HTTP/1.1 201
is returned if the application is successfully created.
The response has the following additional header Location
, containing the applicationId
of the created application:
https://$instanceId.id.nevis.cloud/nevis/api/v1/applications/$applicationId
The applicationId
is a generated UUID.
On failure
HTTP/1.1 401
is returned if the authorization fails due to an invalid access key.
HTTP/1.1 422
is returned if invalid request content is given.
HTTP/1.1 500
is returned if an unexpected error occurs.