Create a Screen

Endpoint URL: {identityDomain} /config/{appId} /flows/{flow} /screens



Description

Creates a new screen. Screens are primarily used as a container for hosting forms.

To create a screen, you must specify all the screen properties (in JSON format) in the request body of your API call. Those properties are:

  • hasUserData. Boolean value that indicates whether the screen displays user data. For example, the confirmAccountDeactivation screen does not display any user data; instead, it simply asks the user to verify that they really do want to deactivate their account. By default, only the editProfile and the emailVerificationRequired screens display user data.
     
  • modal. Boolean value that indicates whether the new screen is a “modal.” With a modal screen, the screen must be completed (or dismissed) before the user can do anything else. By default, all Identity Cloud screens have their modal property set to true except for the editProfile screen.
     
  • name. Name of the new screen. Screen names can contain only letters (either uppercase or lowercase), numbers, and the underscore character. myNewScreen is a valid screen name, as is My_New_Screen. However, my new screen (blank spaces) and my-new-screen (hyphens) are not valid screen names and will generate the following error:
{
    "errors": "Screen name may only include upper or lower case letters, numbers and underscore."
} 

A typical request body will look something like this:

{
    "hasUserData": false,
    "modal": true,
    "name": "testScreen"
}

Note, too that, when you create a new screen, you must specify all three properties (hasUserData, modal, and name) in the request body. If you leave out a property your API call will fail with an error similar to the following:

{
    "errors": "Missing payload argument 'hasUserData'."
}


Respects the API Client Allow List:  No

API Client Permissions

The following table indicates the API clients that can (and the API clients that can't) be used to call this endpoint:

owner
access_issuer
direct_access
direct_read_access
login_client
Yes
No
Yes
No
No


Authentication

This endpoint supports Basic authentication. 

How to Create an Authentication String


Base URL

The base URL for this endpoint is your Configuration API domain followed by /config/ followed by your application ID. For example, if you are in the US region and your application ID is htb8fuhxnf8e38jrzub3c7pfrr, then your base URL would be:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr

Allowed regions are:

  • us 
  • eu 
  • au 
  • sa 
  • cn
  • sg


Sample Request (curl)

This command creates a new screen (testScreen) and associates that screen with the standard flow and the application
htb8fuhxnf8e38jrzub3c7pfrr.

curl -X POST \
  https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/flows/standard/screens \
  -H 'Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=' \
  -H 'Content-Type: application/json' \
  -d '{
    "hasUserData": false,
    "modal": true,
    "name": "testScreen"
  }' 

      Running this command in Postman


Responses

200 OK

Response Example (application/json)

{
    "_self": "/config/z6nzfskmy2f23fazcq5qrrcz7e/flows/standard/screens/testScreen",
    "hasUserData": false,
    "name": "testScreen",
    "modal": true
}

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)


{
  "errors": "Flow not found."
}