Application APIs

1. Overview

This page contains the APIs that are used to manage Applications as well as the Roles of an Application. Here are the APIs:

2. Create an Application

This API is used to create an Application. Specifying an Id on the URI will instruct Passport to use that Id when creating the Application. Otherwise, Passport will generate an Id for the Application.

2.1. Request

Create an Application with a generated Id

URI

POST /api/application

Create an Application with the given Id

URI

POST /api/application/{applicationId}

Table 1. Request Parameters

applicationId [UUID] Optional defaults to a generated UUID

The Id to use for the new Application. If not specified a secure random UUID will be generated.

Table 2. Request Body

application.authenticationTokenConfiguration.enabled [Boolean] Optional defaults to false Available Since 1.14.0

Determines if Users can have Authentication Tokens associated with this Application. This feature may not be enabled for the Passport application.

application.cleanSpeakConfiguration.applicationIds [Array<UUID>] Optional

An array of UUIDs that map to the CleanSpeak applications for this Application. It is possible that a single Application in Passport might have multiple Applications in CleanSpeak. For example, an Passport Application for a game might have one CleanSpeak Application for usernames and another Application for chat.

This property is used when CleanSpeak sends user action notifications to Passport (when users are disciplined for example). Passport will translate the CleanSpeak ids to Passport ids and then apply the user action.

application.cleanSpeakConfiguration.usernameModeration.applicationId [UUID] Optional

The Id of the CleanSpeak application that usernames are sent to for moderation.

application.cleanSpeakConfiguration.usernameModeration.enabled [Boolean] Optional defaults to false

True if CleanSpeak username moderation is enabled.

application.jwtConfiguration.algorithm [String] Optional

The algorithm used to sign the JSON Web Token (JWT). The following available JSON Web Algorithms (JWA) as described in RFC 7518 are available.

  • HS256 - HMAC using SHA-256

  • HS384 - HMAC using SHA-384

  • HS512 - HMAC using SHA-512

  • RS256 - RSASSA-PKCS1-v1_5 using SHA-256

  • RS384 - RSASSA-PKCS1-v1_5 using SHA-384

  • RS512 - RSASSA-PKCS1-v1_5 using SHA-512

  • none - Unsecured

Required when enabled is set to true.

application.jwtConfiguration.enabled [Boolean] Optional Defaults to false

Indicates if this application is using the JWT configuration defined here or the global JWT configuration defined by the System Configuration. If this is false the signing algorithm configured in the System Configuration will be used. If true the signing algorithm defined in this application will be used.

application.jwtConfiguration.privateKey [String] Optional

The private key used when an RSA signing algorithm has been selected. The private key will be used to sign the JWT. This key is expected to be presented in a PEM encoded format.

Required when enabled is set to true and algorithm is set to an RSA based value.

application.jwtConfiguration.publicKey [String] Optional

The public key used when an RSA signing algorithms has been selected. The public key will be used to verify JWTs signed with the private key. This key is expected to be presented in a PEM encoded format.

Required when enabled is set to true and algorithm is set to an RSA based value.

application.jwtConfiguration.refreshTokenTimeToLiveInMinutes [Integer] Optional

The length of time in minutes the JWT refresh token will live before it is expired and is not able to be exchanged for a JWT.

Required when enabled is set to true.

application.jwtConfiguration.secret [String] Optional

The secret used when an HMAC based signing algorithm has been selected. This secret is used to sign and verify JWTs.

Required when enabled is set to true and algorithm is set to an HMAC based value.

application.name [String] Required

The name of the Application.

application.oauthConfiguration.authorizedOriginURLs [Array<String>] Optional

An array of URLs that are the authorized origins for Passport OAuth.

application.oauthConfiguration.authorizedRedirectURLs [Array<String>] Optional

An array of URLs that are the authorized redirect URLs for Passport OAuth.

application.oauthConfiguration.logoutURL [String] Optional

The logout URL for the Application. Passport will redirect to this URL after the user logs out of OAuth.

application.roles [Array] Optional

An array of Role objects.

application.roles[x].description [String] Optional

A description for the role.

application.roles[x].id [UUID] Optional generated if null

The Id of the Role.

application.roles[x].name [String] Required

The name of the Role.

application.roles[x].isDefault [Boolean] Optional defaults to false

Whether or not the Role is a default role. A default role is automatically assigned to a user during registration if no roles are provided.

application.verificationEmailTemplateId [UUID] Optional Available Since 1.21.0

The Id of the Email Template that is used to send the Registration Verification emails to users. If the verifyRegistration field is true this field is required.

application.verifyRegistration [Boolean] Optional Defaults to false Available Since 1.21.0

Whether or not registrations to this Application may be verified. When this is set to true the verificationEmailTemplateId parameter is also required.

webhookIds [Array<UUID>] Optional

An array of Webhook Ids. For Webhooks that are not already configured for All Applications, specifying an Id on this request will indicate the associated Webhook should handle events for this application.

Example Request JSON
{
  "application": {
    "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
    "active": true,
    "cleanSpeakConfiguration": {
      "applicationIds": [
        "6b4253e0-cee0-47dd-973a-a27b9e23987c",
        "76a556ec-4ba8-4140-9085-555ee9a8bb1a"
      ],
      "usernameModeration": {
        "applicationId": "2338dc41-bed0-4cdb-8251-ac68701e9bc7",
        "enabled": true
      }
    },
    "jwtConfiguration": {
      "algorithm": "HS256",
      "enabled": true,
      "secret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
      "timeToLiveInSeconds": 3600
    },
    "name": "Forum",
    "oauthConfiguration": {
      "authorizedOriginURLs": [
        "http://www.example.com"
      ],
      "authorizedRedirectURLs": [
        "http://www.example.com/oauth-callback"
      ],
      "clientSecret": "some-cool-secret",
      "logoutURL": "http://www.example.com/logout"
    },
    "roles": [
      {
        "description": "Administrators that have access to everything",
        "id": "ce485a91-906f-4615-af75-81d37dc71e90",
        "name": "admin",
        "isDefault": false
      },
      {
        "description": "Normal users that have access to nothing",
        "id": "ce485a91-906f-4615-af75-81d37dc71e91",
        "name": "user",
        "isDefault": true
      }
    ]
  },
  "webhookIds": [
    "00000000-0000-0000-0000-000000000042"
  ]
}

2.2. Response

The response for this API contains the information for the Application that was created.

Table 3. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

Table 4. Response Body for a single Application

application.id [UUID]

The Id of the Application.

application.active [Boolean]

Whether or not the Application is active.

application.authenticationTokenConfiguration.enabled [Boolean] Available Since 1.14.0

Whether or not Users can have Authentication Tokens associated with this Application.

application.cleanSpeakConfiguration.applicationIds [Array<UUID>]

An array of UUIDs that map to the CleanSpeak applications for this Application. It is possible that a single Application in Passport might have multiple Applications in CleanSpeak. For example, an Passport Application for a game might have one CleanSpeak Application for usernames and another Application for chat.

This property is used when CleanSpeak sends user action notifications to Passport (when users are disciplined for example). Passport will translate the CleanSpeak ids to Passport ids and then apply the user action.

application.cleanSpeakConfiguration.enabled [Boolean]

True if CleanSpeak integration is enabled. This setting is global and is not modifiable using this API.

application.cleanSpeakConfiguration.usernameModeration.applicationId [UUID]

The Id of the CleanSpeak application that usernames are sent to for moderation.

application.cleanSpeakConfiguration.usernameModeration.enabled [Boolean]

True if CleanSpeak username moderation is enabled.

application.jwtConfiguration.algorithm [String]

The algorithm used to sign the JSON Web Token (JWT). The following available JSON Web Algorithms (JWA) as described in RFC 7518 are available.

  • HS256 - HMAC using SHA-256

  • HS384 - HMAC using SHA-384

  • HS512 - HMAC using SHA-512

  • RS256 - RSASSA-PKCS1-v1_5 using SHA-256

  • RS384 - RSASSA-PKCS1-v1_5 using SHA-384

  • RS512 - RSASSA-PKCS1-v1_5 using SHA-512

  • none - Unsecured

application.jwtConfiguration.enabled [Boolean]

Indicates if this application is using the JWT configuration defined here or the global JWT configuration defined by the System Configuration. If this is false the signing algorithm configured in the System Configuration will be used. If true the signing algorithm defined in this application will be used.

application.jwtConfiguration.privateKey [String]

The private key used when an RSA signing algorithm has been selected. The private key will be used to sign the JWT. This key will be returned in a PEM encoded format.

application.jwtConfiguration.publicKey [String]

The public key used when an RSA signing algorithms has been selected. The public key will be used to verify JWTs signed with the private key. This key will be returned in a PEM encoded format.

application.jwtConfiguration.refreshTokenTimeToLiveInMinutes [Integer]

The length of time in minutes the JWT refresh token will live before it is expired and is not able to be exchanged for a JWT.

application.jwtConfiguration.secret [String]

The secret used when an HMAC based signing algorithm has been selected. This secret is used to sign and verify JWTs.

application.name [String]

The name of the Application.

application.oauthConfiguration.authorizedOriginURLs [Array<String>]

An array of URLs that are the authorized origins for Passport OAuth.

application.oauthConfiguration.authorizedRedirectURLs [Array<String>]

An array of URLs that are the authorized redirect URLs for Passport OAuth.

application.oauthConfiguration.clientId [String]

The OAuth client Id of the Application.

application.oauthConfiguration.clientSecret [String]

The OAuth client secret.

application.oauthConfiguration.logoutURL [String]

The logout URL for the Application. Passport will redirect to this URL after the user logs out of OAuth.

application.verificationEmailTemplateId [UUID] Available Since 1.21.0

The Id of the Email Template that is used to send the Registration Verification emails to users.

application.verifyRegistration [Boolean] Available Since 1.21.0

Whether or not registrations to this Application may be verified.

application.roles [Array]

An array of Role objects.

application.roles[x].description [String]

A description of the role.

application.roles[x].id [UUID]

The Id of the Role.

application.roles[x].name [String]

The name of the Role.

application.roles[x].isDefault [Boolean]

Whether or not the Role is a default role. A default role is automatically assigned to a user during registration if no roles are provided.

application.roles[x].isSuperRole [Boolean] Available Since 1.8.1

Whether or not the Role is a considered to be a super user role. This is a marker to indicate that it supersedes all other roles. Passport will attempt to enforce this contract when using the web UI, it is not enforced programmatically when using the API.

Example Response JSON for a Single Application
{
  "application": {
    "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
    "active": true,
    "cleanSpeakConfiguration": {
      "applicationIds": [
        "6b4253e0-cee0-47dd-973a-a27b9e23987c",
        "76a556ec-4ba8-4140-9085-555ee9a8bb1a"
      ],
      "enabled": true,
      "usernameModeration": {
        "applicationId": "2338dc41-bed0-4cdb-8251-ac68701e9bc7",
        "enabled": true
      }
    },
    "jwtConfiguration": {
      "algorithm": "HS256",
      "enabled": true,
      "secret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
      "timeToLiveInSeconds": 3600
    },
    "name": "Forum",
    "oauthConfiguration": {
      "authorizedOriginURLs": [
        "http://www.example.com"
      ],
      "authorizedRedirectURLs": [
        "http://www.example.com/oauth-callback"
      ],
      "clientId": "dfbd1210-2818-4353-adb2-952613eb5d96",
      "logoutURL": "http://www.example.com/logout"
    },
    "roles": [
      {
        "description": "Administrators that have access to everything",
        "id": "ce485a91-906f-4615-af75-81d37dc71e90",
        "name": "admin",
        "isDefault": false
      },
      {
        "description": "Normal users that have access to nothing",
        "id": "ce485a91-906f-4615-af75-81d37dc71e91",
        "name": "user",
        "isDefault": true
      }
    ]
  }
}

3. Retrieve an Application

This API is used to retrieve one or all of the configured Applications. Specifying an Id on the URI will retrieve a single Application. Leaving off the Id will retrieve all of the Applications.

3.1. Request

Retrieve all of the active Applications

URI

GET /api/application

Retrieve all of the inactive Applications

URI

GET /api/application?inactive=true

Table 5. Request Parameters

inactive [Boolean] Optional

Set this parameter to true in order to retrieve only inactive Applications. Setting this parameter to false is equivalent omitting the inactive parameter.

Retrieve a single Application by Id

URI

GET /api/application/{applicationId}

Table 6. Request Parameters

applicationId [UUID] Optional

The Id of the Application to retrieve. This request will return the Application if it exists regardless if the Application is active or not.

3.2. Response

The response for this API contains either a single Application or all of the Applications. When you call this API with an Id the response will contain just that Application. When you call this API without an Id the response will contain all of the Applications. Both response types are defined below along with an example JSON response.

Table 7. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

404

The object you requested doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

Table 8. Response Body for a single Application

application.id [UUID]

The Id of the Application.

application.active [Boolean]

Whether or not the Application is active.

application.authenticationTokenConfiguration.enabled [Boolean] Available Since 1.14.0

Whether or not Users can have Authentication Tokens associated with this Application.

application.cleanSpeakConfiguration.applicationIds [Array<UUID>]

An array of UUIDs that map to the CleanSpeak applications for this Application. It is possible that a single Application in Passport might have multiple Applications in CleanSpeak. For example, an Passport Application for a game might have one CleanSpeak Application for usernames and another Application for chat.

This property is used when CleanSpeak sends user action notifications to Passport (when users are disciplined for example). Passport will translate the CleanSpeak ids to Passport ids and then apply the user action.

application.cleanSpeakConfiguration.enabled [Boolean]

True if CleanSpeak integration is enabled. This setting is global and is not modifiable using this API.

application.cleanSpeakConfiguration.usernameModeration.applicationId [UUID]

The Id of the CleanSpeak application that usernames are sent to for moderation.

application.cleanSpeakConfiguration.usernameModeration.enabled [Boolean]

True if CleanSpeak username moderation is enabled.

application.jwtConfiguration.algorithm [String]

The algorithm used to sign the JSON Web Token (JWT). The following available JSON Web Algorithms (JWA) as described in RFC 7518 are available.

  • HS256 - HMAC using SHA-256

  • HS384 - HMAC using SHA-384

  • HS512 - HMAC using SHA-512

  • RS256 - RSASSA-PKCS1-v1_5 using SHA-256

  • RS384 - RSASSA-PKCS1-v1_5 using SHA-384

  • RS512 - RSASSA-PKCS1-v1_5 using SHA-512

  • none - Unsecured

application.jwtConfiguration.enabled [Boolean]

Indicates if this application is using the JWT configuration defined here or the global JWT configuration defined by the System Configuration. If this is false the signing algorithm configured in the System Configuration will be used. If true the signing algorithm defined in this application will be used.

application.jwtConfiguration.privateKey [String]

The private key used when an RSA signing algorithm has been selected. The private key will be used to sign the JWT. This key will be returned in a PEM encoded format.

application.jwtConfiguration.publicKey [String]

The public key used when an RSA signing algorithms has been selected. The public key will be used to verify JWTs signed with the private key. This key will be returned in a PEM encoded format.

application.jwtConfiguration.refreshTokenTimeToLiveInMinutes [Integer]

The length of time in minutes the JWT refresh token will live before it is expired and is not able to be exchanged for a JWT.

application.jwtConfiguration.secret [String]

The secret used when an HMAC based signing algorithm has been selected. This secret is used to sign and verify JWTs.

application.name [String]

The name of the Application.

application.oauthConfiguration.authorizedOriginURLs [Array<String>]

An array of URLs that are the authorized origins for Passport OAuth.

application.oauthConfiguration.authorizedRedirectURLs [Array<String>]

An array of URLs that are the authorized redirect URLs for Passport OAuth.

application.oauthConfiguration.clientId [String]

The OAuth client Id of the Application.

application.oauthConfiguration.clientSecret [String]

The OAuth client secret.

application.oauthConfiguration.logoutURL [String]

The logout URL for the Application. Passport will redirect to this URL after the user logs out of OAuth.

application.verificationEmailTemplateId [UUID] Available Since 1.21.0

The Id of the Email Template that is used to send the Registration Verification emails to users.

application.verifyRegistration [Boolean] Available Since 1.21.0

Whether or not registrations to this Application may be verified.

application.roles [Array]

An array of Role objects.

application.roles[x].description [String]

A description of the role.

application.roles[x].id [UUID]

The Id of the Role.

application.roles[x].name [String]

The name of the Role.

application.roles[x].isDefault [Boolean]

Whether or not the Role is a default role. A default role is automatically assigned to a user during registration if no roles are provided.

application.roles[x].isSuperRole [Boolean] Available Since 1.8.1

Whether or not the Role is a considered to be a super user role. This is a marker to indicate that it supersedes all other roles. Passport will attempt to enforce this contract when using the web UI, it is not enforced programmatically when using the API.

Example Response JSON for a Single Application
{
  "application": {
    "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
    "active": true,
    "cleanSpeakConfiguration": {
      "applicationIds": [
        "6b4253e0-cee0-47dd-973a-a27b9e23987c",
        "76a556ec-4ba8-4140-9085-555ee9a8bb1a"
      ],
      "enabled": true,
      "usernameModeration": {
        "applicationId": "2338dc41-bed0-4cdb-8251-ac68701e9bc7",
        "enabled": true
      }
    },
    "jwtConfiguration": {
      "algorithm": "HS256",
      "enabled": true,
      "secret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
      "timeToLiveInSeconds": 3600
    },
    "name": "Forum",
    "oauthConfiguration": {
      "authorizedOriginURLs": [
        "http://www.example.com"
      ],
      "authorizedRedirectURLs": [
        "http://www.example.com/oauth-callback"
      ],
      "clientId": "dfbd1210-2818-4353-adb2-952613eb5d96",
      "logoutURL": "http://www.example.com/logout"
    },
    "roles": [
      {
        "description": "Administrators that have access to everything",
        "id": "ce485a91-906f-4615-af75-81d37dc71e90",
        "name": "admin",
        "isDefault": false
      },
      {
        "description": "Normal users that have access to nothing",
        "id": "ce485a91-906f-4615-af75-81d37dc71e91",
        "name": "user",
        "isDefault": true
      }
    ]
  }
}
Table 9. Response Body for all Applications

applications [Array]

The list of Application objects.

applications[x].id [UUID]

The Id of the Application.

applications[x].active [Boolean]

Whether or not the Application is active.

applications[x].authenticationTokenConfiguration.enabled [Boolean]

Whether or not Users can have Authentication Tokens associated with this Application.

applications[x].cleanSpeakConfiguration.applicationIds [Array<UUID>]

An array of UUIDs that map to the CleanSpeak applications for this Application. It is possible that a single Application in Passport might have multiple Applications in CleanSpeak. For example, an Passport Application for a game might have one CleanSpeak Application for usernames and another Application for chat.

This property is used when CleanSpeak sends user action notifications to Passport (when users are disciplined for example). Passport will translate the CleanSpeak ids to Passport ids and then apply the user action.

application[x].cleanSpeakConfiguration.enabled [Boolean]

True if CleanSpeak integration is enabled. This setting is global and is not modifiable using this API.

applications[x].cleanSpeakConfiguration.usernameModeration.applicationId [UUID]

The Id of the CleanSpeak application that usernames are sent to for moderation.

applications[x].cleanSpeakConfiguration.usernameModeration.enabled [Boolean]

True if CleanSpeak username moderation is enabled.

applications[x].name [String]

The name of the Application.

application[x].jwtConfiguration.algorithm [String]

The algorithm used to sign the JSON Web Token (JWT). The following available JSON Web Algorithms (JWA) as described in RFC 7518 are available.

  • HS256 - HMAC using SHA-256

  • HS384 - HMAC using SHA-384

  • HS512 - HMAC using SHA-512

  • RS256 - RSASSA-PKCS1-v1_5 using SHA-256

  • RS384 - RSASSA-PKCS1-v1_5 using SHA-384

  • RS512 - RSASSA-PKCS1-v1_5 using SHA-512

  • none - Unsecured

application[x].jwtConfiguration.enabled [Boolean]

Indicates if this application is using the JWT configuration defined here or the global JWT configuration defined by the System Configuration. If this is false the signing algorithm configured in the System Configuration will be used. If true the signing algorithm defined in this application will be used.

application[x].jwtConfiguration.privateKey [String]

The private key used when an RSA signing algorithm has been selected. The private key will be used to sign the JWT. This key will be returned in a PEM encoded format.

application[x].jwtConfiguration.publicKey [String]

The public key used when an RSA signing algorithms has been selected. The public key will be used to verify JWTs signed with the private key. This key will be returned in a PEM encoded format.

application[x].jwtConfiguration.refreshTokenTimeToLiveInMinutes [Integer]

The length of time in minutes the JWT refresh token will live before it is expired and is not able to be exchanged for a JWT.

application[x].jwtConfiguration.secret [String]

The secret used when an HMAC based signing algorithm has been selected. This secret is used to sign and verify JWTs.

applications[x].oauthConfiguration.authorizedOriginURLs [Array<String>]

An array of URLs that are the authorized origins for Passport OAuth.

applications[x].oauthConfiguration.authorizedRedirectURLs [Array<String>]

An array of URLs that are the authorized redirect URLs for Passport OAuth.

applications[x].oauthConfiguration.clientId [String]

The OAuth client Id of the Application.

applications[x].oauthConfiguration.clientSecret [String]

The OAuth client secret.

applications[x].oauthConfiguration.logoutURL [String]

The logout URL for the Application. Passport will redirect to this URL after the user logs out of OAuth.

applications[x].verificationEmailTemplateId [UUID] Available Since 1.21.0

The Id of the Email Template that is used to send the Registration Verification emails to users. If the verifyRegistration field is true this field is required.

applications[x].verifyRegistration [Boolean] Available Since 1.21.0

Whether or not registrations to this Application may be verified. When this is set to true the verificationEmailTemplateId parameter is also required.

applications[x].roles [Array]

An array of Role objects.

applications[x].roles[x].description [String]

A description of the role.

applications[x].roles[x].id [UUID]

The Id of the Role.

applications[x].roles[x].name [String]

The name of the Role.

applications[x].roles[x].isDefault [Boolean]

Whether or not the Role is a default role. A default role is automatically assigned to a user during registration if no roles are provided.

Example Response JSON for all the Applications
{
  "applications": [
    {
      "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
      "active": true,
      "cleanSpeakConfiguration": {
        "applicationIds": [
          "6b4253e0-cee0-47dd-973a-a27b9e23987c",
          "76a556ec-4ba8-4140-9085-555ee9a8bb1a"
        ],
        "usernameModeration": {
          "applicationId": "2338dc41-bed0-4cdb-8251-ac68701e9bc7",
          "enabled" : true
        }
      },
      "jwtConfiguration": {
        "algorithm": "HS256",
        "enabled": true,
        "secret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
        "timeToLiveInSeconds": 3600
      },
      "name": "Forum",
      "oauthConfiguration": {
        "authorizedOriginURLs": [
          "http://www.example.com"
        ],
        "authorizedRedirectURLs": [
          "http://www.example.com/oauth-callback"
        ],
        "clientId": "dfbd1210-2818-4353-adb2-952613eb5d96",
        "logoutURL": "http://www.example.com/logout"
      },
      "roles": [
        {
          "description": "Administrators that have access to everything",
          "id": "ce485a91-906f-4615-af75-81d37dc71e90",
          "name": "admin",
          "isDefault": false
        },
        {
          "description": "Normal users that have access to nothing",
          "id": "ce485a91-906f-4615-af75-81d37dc71e91",
          "name": "user",
          "isDefault": true
        }
      ]
    }
  ]
}

4. Update an Application

This API is used to update an existing Application. You must specify the Id of the Application you are updating on the URI. You must specify all of the properties of the Application when calling this API. This API doesn’t merge the existing Application and your new data. It replaces the existing Application with your new data.

You can’t update an Application’s roles via this API. This prevents you from accidentally removing all the roles of an Application. To create, update or remove a role from the Application, you need to call one of these APIs:

4.1. Request

Update an Application by Id

URI

PUT /api/application{applicationId}

Table 10. Request Body

application.authenticationTokenConfiguration.enabled [Boolean] Optional Available Since 1.14.0

Determines if Users can have Authentication Tokens associated with this Application. This feature may not be enabled for the Passport application.

application.cleanSpeakConfiguration.applicationIds [Array<UUID>] Optional

An array of UUIDs that map to the CleanSpeak applications for this Application. It is possible that a single Application in Passport might have multiple Applications in CleanSpeak. For example, an Passport Application for a game might have one CleanSpeak Application for usernames and another Application for chat.

This property is used when CleanSpeak sends user action notifications to Passport (when users are disciplined for example). Passport will translate the CleanSpeak ids to Passport ids and then apply the user action.

application.cleanSpeakConfiguration.usernameModeration.applicationId [UUID] Optional

The Id of the CleanSpeak application that usernames are sent to for moderation.

application.cleanSpeakConfiguration.usernameModeration.enabled [Boolean] Optional defaults to false

True if CleanSpeak username moderation is enabled.

application.jwtConfiguration.algorithm [String] Optional

The algorithm used to sign the JSON Web Token (JWT). The following available JSON Web Algorithms (JWA) as described in RFC 7518 are available.

  • HS256 - HMAC using SHA-256

  • HS384 - HMAC using SHA-384

  • HS512 - HMAC using SHA-512

  • RS256 - RSASSA-PKCS1-v1_5 using SHA-256

  • RS384 - RSASSA-PKCS1-v1_5 using SHA-384

  • RS512 - RSASSA-PKCS1-v1_5 using SHA-512

  • none - Unsecured

application.jwtConfiguration.enabled [Boolean] Optional Defaults to false

Indicates if this application is using the JWT configuration defined here or the global JWT configuration defined by the System Configuration. If this is false the signing algorithm configured in the System Configuration will be used. If true the signing algorithm defined in this application will be used.

application.jwtConfiguration.privateKey [String] Optional

The private key used when an RSA signing algorithm has been selected. The private key will be used to sign the JWT. This key will be returned in a PEM encoded format.

Required when enabled is set to true and algorithm is set to an RSA based value.

application.jwtConfiguration.publicKey [String] Optional

The public key used when an RSA signing algorithms has been selected. The public key will be used to verify JWTs signed with the private key. This key will be returned in a PEM encoded format.

Required when enabled is set to true and algorithm is set to an RSA based value.

application.jwtConfiguration.refreshTokenTimeToLiveInMinutes [Integer] Optional

The length of time in minutes the JWT refresh token will live before it is expired and is not able to be exchanged for a JWT.

Required when enabled is set to true.

application.jwtConfiguration.secret [String] Optional

The secret used when an HMAC based signing algorithm has been selected. This secret is used to sign and verify JWTs.

Required when enabled is set to true and algorithm is set to an HMAC based value.

application.name [String] Required

The name of the Application.

application.oauthConfiguration.authorizedOriginURLs [Array<String>] Optional

An array of URLs that are the authorized origins for Passport OAuth.

application.oauthConfiguration.authorizedRedirectURLs [Array<String>] Optional

An array of URLs that are the authorized redirect URLs for Passport OAuth.

application.oauthConfiguration.logoutURL [String] Optional

The logout URL for the Application. Passport will redirect to this URL after the user logs out of OAuth.

application.verificationEmailTemplateId [UUID] Optional Available Since 1.21.0

The Id of the Email Template that is used to send the Registration Verification emails to users. If the verifyRegistration field is true this field is required.

application.verifyRegistration [Boolean] Optional Defaults to false Available Since 1.21.0

Whether or not registrations to this Application may be verified. When this is set to true the verificationEmailTemplateId parameter is also required.

webhookIds [Array<UUID>] Optional

An array of Webhook Ids. For Webhooks that are not already configured for All Applications, specifying an Id on this request will indicate the associated Webhook should handle events for this application.

Example Request JSON
{
  "application": {
    "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
    "active": true,
    "cleanSpeakConfiguration": {
      "applicationIds": [
        "6b4253e0-cee0-47dd-973a-a27b9e23987c",
        "76a556ec-4ba8-4140-9085-555ee9a8bb1a"
      ],
      "usernameModeration": {
        "applicationId": "2338dc41-bed0-4cdb-8251-ac68701e9bc7",
        "enabled": true
      }
    },
    "jwtConfiguration": {
      "algorithm": "HS256",
      "enabled": true,
      "secret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
      "timeToLiveInSeconds": 3600
    },
    "name": "Forum",
    "oauthConfiguration": {
      "authorizedOriginURLs": [
        "http://www.example.com"
      ],
      "authorizedRedirectURLs": [
        "http://www.example.com/oauth-callback"
      ],
      "logoutURL": "http://www.example.com/logout"
    }
  },
  "webhookIds": [
    "00000000-0000-0000-0000-000000000042"
  ]
}

4.2. Response

The response for this API contains the new information for the Application that was updated.

Table 11. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

404

The object you are trying to updated doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

Table 12. Response Body for a single Application

application.id [UUID]

The Id of the Application.

application.active [Boolean]

Whether or not the Application is active.

application.authenticationTokenConfiguration.enabled [Boolean] Available Since 1.14.0

Whether or not Users can have Authentication Tokens associated with this Application.

application.cleanSpeakConfiguration.applicationIds [Array<UUID>]

An array of UUIDs that map to the CleanSpeak applications for this Application. It is possible that a single Application in Passport might have multiple Applications in CleanSpeak. For example, an Passport Application for a game might have one CleanSpeak Application for usernames and another Application for chat.

This property is used when CleanSpeak sends user action notifications to Passport (when users are disciplined for example). Passport will translate the CleanSpeak ids to Passport ids and then apply the user action.

application.cleanSpeakConfiguration.enabled [Boolean]

True if CleanSpeak integration is enabled. This setting is global and is not modifiable using this API.

application.cleanSpeakConfiguration.usernameModeration.applicationId [UUID]

The Id of the CleanSpeak application that usernames are sent to for moderation.

application.cleanSpeakConfiguration.usernameModeration.enabled [Boolean]

True if CleanSpeak username moderation is enabled.

application.jwtConfiguration.algorithm [String]

The algorithm used to sign the JSON Web Token (JWT). The following available JSON Web Algorithms (JWA) as described in RFC 7518 are available.

  • HS256 - HMAC using SHA-256

  • HS384 - HMAC using SHA-384

  • HS512 - HMAC using SHA-512

  • RS256 - RSASSA-PKCS1-v1_5 using SHA-256

  • RS384 - RSASSA-PKCS1-v1_5 using SHA-384

  • RS512 - RSASSA-PKCS1-v1_5 using SHA-512

  • none - Unsecured

application.jwtConfiguration.enabled [Boolean]

Indicates if this application is using the JWT configuration defined here or the global JWT configuration defined by the System Configuration. If this is false the signing algorithm configured in the System Configuration will be used. If true the signing algorithm defined in this application will be used.

application.jwtConfiguration.privateKey [String]

The private key used when an RSA signing algorithm has been selected. The private key will be used to sign the JWT. This key will be returned in a PEM encoded format.

application.jwtConfiguration.publicKey [String]

The public key used when an RSA signing algorithms has been selected. The public key will be used to verify JWTs signed with the private key. This key will be returned in a PEM encoded format.

application.jwtConfiguration.refreshTokenTimeToLiveInMinutes [Integer]

The length of time in minutes the JWT refresh token will live before it is expired and is not able to be exchanged for a JWT.

application.jwtConfiguration.secret [String]

The secret used when an HMAC based signing algorithm has been selected. This secret is used to sign and verify JWTs.

application.name [String]

The name of the Application.

application.oauthConfiguration.authorizedOriginURLs [Array<String>]

An array of URLs that are the authorized origins for Passport OAuth.

application.oauthConfiguration.authorizedRedirectURLs [Array<String>]

An array of URLs that are the authorized redirect URLs for Passport OAuth.

application.oauthConfiguration.clientId [String]

The OAuth client Id of the Application.

application.oauthConfiguration.clientSecret [String]

The OAuth client secret.

application.oauthConfiguration.logoutURL [String]

The logout URL for the Application. Passport will redirect to this URL after the user logs out of OAuth.

application.verificationEmailTemplateId [UUID] Available Since 1.21.0

The Id of the Email Template that is used to send the Registration Verification emails to users.

application.verifyRegistration [Boolean] Available Since 1.21.0

Whether or not registrations to this Application may be verified.

application.roles [Array]

An array of Role objects.

application.roles[x].description [String]

A description of the role.

application.roles[x].id [UUID]

The Id of the Role.

application.roles[x].name [String]

The name of the Role.

application.roles[x].isDefault [Boolean]

Whether or not the Role is a default role. A default role is automatically assigned to a user during registration if no roles are provided.

application.roles[x].isSuperRole [Boolean] Available Since 1.8.1

Whether or not the Role is a considered to be a super user role. This is a marker to indicate that it supersedes all other roles. Passport will attempt to enforce this contract when using the web UI, it is not enforced programmatically when using the API.

Example Response JSON for a Single Application
{
  "application": {
    "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
    "active": true,
    "cleanSpeakConfiguration": {
      "applicationIds": [
        "6b4253e0-cee0-47dd-973a-a27b9e23987c",
        "76a556ec-4ba8-4140-9085-555ee9a8bb1a"
      ],
      "enabled": true,
      "usernameModeration": {
        "applicationId": "2338dc41-bed0-4cdb-8251-ac68701e9bc7",
        "enabled": true
      }
    },
    "jwtConfiguration": {
      "algorithm": "HS256",
      "enabled": true,
      "secret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
      "timeToLiveInSeconds": 3600
    },
    "name": "Forum",
    "oauthConfiguration": {
      "authorizedOriginURLs": [
        "http://www.example.com"
      ],
      "authorizedRedirectURLs": [
        "http://www.example.com/oauth-callback"
      ],
      "clientId": "dfbd1210-2818-4353-adb2-952613eb5d96",
      "logoutURL": "http://www.example.com/logout"
    },
    "roles": [
      {
        "description": "Administrators that have access to everything",
        "id": "ce485a91-906f-4615-af75-81d37dc71e90",
        "name": "admin",
        "isDefault": false
      },
      {
        "description": "Normal users that have access to nothing",
        "id": "ce485a91-906f-4615-af75-81d37dc71e91",
        "name": "user",
        "isDefault": true
      }
    ]
  }
}

5. Delete an Application

This API is used to delete an Application. You must specify the Id of the Application on the URI. You can also specify whether or not the Application is soft or hard deleted. Soft deleted Applications are marked as inactive but not deleted from Passport.

5.1. Request

Soft delete an Application. This operation can be reversed by re-activating the Application.

URI

DELETE /api/application/{applicationId}

Permanently delete an Application. This operation cannot be reversed.

URI

DELETE /api/application/{applicationId}?hardDelete=true

Table 13. Request Parameters

applicationId [UUID] Required

The Id of the Application to delete.

hardDelete [Boolean] Optional

Whether or not the Application is soft or hard deleted. A hard delete is a permanent operation.

5.2. Response

This API does not return a JSON response body.

Table 14. Response Codes
Code Description

200

The request was successful. The response will be empty.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

404

The object you are trying to delete doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

6. Reactivate an Application

This API is used to reactivate an inactive Application. You must specify the Id of the Application on the URI.

6.1. Request

Reactivate the Application

URI

PUT /api/application/{applicationId}?reactivate=true

Table 15. Request Parameters

applicationId [UUID] Required

The Id of the Application to reactivate.

6.2. Response

The response for this API contains the information for the Application that was reactivated.

Table 16. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

404

The object you requested doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

Table 17. Response Body for a single Application

application.id [UUID]

The Id of the Application.

application.active [Boolean]

Whether or not the Application is active.

application.authenticationTokenConfiguration.enabled [Boolean] Available Since 1.14.0

Whether or not Users can have Authentication Tokens associated with this Application.

application.cleanSpeakConfiguration.applicationIds [Array<UUID>]

An array of UUIDs that map to the CleanSpeak applications for this Application. It is possible that a single Application in Passport might have multiple Applications in CleanSpeak. For example, an Passport Application for a game might have one CleanSpeak Application for usernames and another Application for chat.

This property is used when CleanSpeak sends user action notifications to Passport (when users are disciplined for example). Passport will translate the CleanSpeak ids to Passport ids and then apply the user action.

application.cleanSpeakConfiguration.enabled [Boolean]

True if CleanSpeak integration is enabled. This setting is global and is not modifiable using this API.

application.cleanSpeakConfiguration.usernameModeration.applicationId [UUID]

The Id of the CleanSpeak application that usernames are sent to for moderation.

application.cleanSpeakConfiguration.usernameModeration.enabled [Boolean]

True if CleanSpeak username moderation is enabled.

application.jwtConfiguration.algorithm [String]

The algorithm used to sign the JSON Web Token (JWT). The following available JSON Web Algorithms (JWA) as described in RFC 7518 are available.

  • HS256 - HMAC using SHA-256

  • HS384 - HMAC using SHA-384

  • HS512 - HMAC using SHA-512

  • RS256 - RSASSA-PKCS1-v1_5 using SHA-256

  • RS384 - RSASSA-PKCS1-v1_5 using SHA-384

  • RS512 - RSASSA-PKCS1-v1_5 using SHA-512

  • none - Unsecured

application.jwtConfiguration.enabled [Boolean]

Indicates if this application is using the JWT configuration defined here or the global JWT configuration defined by the System Configuration. If this is false the signing algorithm configured in the System Configuration will be used. If true the signing algorithm defined in this application will be used.

application.jwtConfiguration.privateKey [String]

The private key used when an RSA signing algorithm has been selected. The private key will be used to sign the JWT. This key will be returned in a PEM encoded format.

application.jwtConfiguration.publicKey [String]

The public key used when an RSA signing algorithms has been selected. The public key will be used to verify JWTs signed with the private key. This key will be returned in a PEM encoded format.

application.jwtConfiguration.refreshTokenTimeToLiveInMinutes [Integer]

The length of time in minutes the JWT refresh token will live before it is expired and is not able to be exchanged for a JWT.

application.jwtConfiguration.secret [String]

The secret used when an HMAC based signing algorithm has been selected. This secret is used to sign and verify JWTs.

application.name [String]

The name of the Application.

application.oauthConfiguration.authorizedOriginURLs [Array<String>]

An array of URLs that are the authorized origins for Passport OAuth.

application.oauthConfiguration.authorizedRedirectURLs [Array<String>]

An array of URLs that are the authorized redirect URLs for Passport OAuth.

application.oauthConfiguration.clientId [String]

The OAuth client Id of the Application.

application.oauthConfiguration.clientSecret [String]

The OAuth client secret.

application.oauthConfiguration.logoutURL [String]

The logout URL for the Application. Passport will redirect to this URL after the user logs out of OAuth.

application.verificationEmailTemplateId [UUID] Available Since 1.21.0

The Id of the Email Template that is used to send the Registration Verification emails to users.

application.verifyRegistration [Boolean] Available Since 1.21.0

Whether or not registrations to this Application may be verified.

application.roles [Array]

An array of Role objects.

application.roles[x].description [String]

A description of the role.

application.roles[x].id [UUID]

The Id of the Role.

application.roles[x].name [String]

The name of the Role.

application.roles[x].isDefault [Boolean]

Whether or not the Role is a default role. A default role is automatically assigned to a user during registration if no roles are provided.

application.roles[x].isSuperRole [Boolean] Available Since 1.8.1

Whether or not the Role is a considered to be a super user role. This is a marker to indicate that it supersedes all other roles. Passport will attempt to enforce this contract when using the web UI, it is not enforced programmatically when using the API.

Example Response JSON for a Single Application
{
  "application": {
    "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
    "active": true,
    "cleanSpeakConfiguration": {
      "applicationIds": [
        "6b4253e0-cee0-47dd-973a-a27b9e23987c",
        "76a556ec-4ba8-4140-9085-555ee9a8bb1a"
      ],
      "enabled": true,
      "usernameModeration": {
        "applicationId": "2338dc41-bed0-4cdb-8251-ac68701e9bc7",
        "enabled": true
      }
    },
    "jwtConfiguration": {
      "algorithm": "HS256",
      "enabled": true,
      "secret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
      "timeToLiveInSeconds": 3600
    },
    "name": "Forum",
    "oauthConfiguration": {
      "authorizedOriginURLs": [
        "http://www.example.com"
      ],
      "authorizedRedirectURLs": [
        "http://www.example.com/oauth-callback"
      ],
      "clientId": "dfbd1210-2818-4353-adb2-952613eb5d96",
      "logoutURL": "http://www.example.com/logout"
    },
    "roles": [
      {
        "description": "Administrators that have access to everything",
        "id": "ce485a91-906f-4615-af75-81d37dc71e90",
        "name": "admin",
        "isDefault": false
      },
      {
        "description": "Normal users that have access to nothing",
        "id": "ce485a91-906f-4615-af75-81d37dc71e91",
        "name": "user",
        "isDefault": true
      }
    ]
  }
}

7. Create an Application Role

This API is used to create a role for an Application. Specifying an Id on the URI will instruct Passport to use that Id when creating the role. Otherwise, Passport will generate an Id for the role.

7.1. Request

Create a Role with a generated Id

URI

POST /api/application/{applicationId}/role

Create a Role with a given Id

URI

POST /api/application/{applicationId}/role/{roleId}

Table 18. Request Parameters

applicationId [UUID] Required

The Id of the Application.

roleId [UUID] Optional defaults to secure random UUID

The Id to use for the new role. If not specified a secure random UUID will be generated.

Table 19. Request Body

role.description [String] Optional

A description for the role.

role.name [String] Required

The name of the Role.

role.isDefault [Boolean] Optional defaults to false

Whether or not the Role is a default role. A default role is automatically assigned to a user during registration if no roles are provided.

role.isSuperRole [Boolean] Optional defaults to false Available Since 1.8.1

Whether or not the Role is a considered to be a super user role. This is a marker to indicate that it supersedes all other roles. Passport will attempt to enforce this contract when using the web UI, it is not enforced programmatically when using the API.

Example Request JSON
{
  "role": {
    "description": "a new role for the app",
    "name": "role 3",
    "isDefault": true
  }
}

7.2. Response

The response for this API contains the information for the role that was created.

Table 20. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

Table 21. Response Body

role.description [String]

The description of the role.

role.id [UUID]

The Id of the Role.

role.name [String]

The name of the Role.

role.isDefault [Boolean]

Whether or not the Role is a default role. A default role is automatically assigned to a user during registration if no roles are provided.

role.isSuperRole [Boolean] Available Since 1.8.1

Whether or not the Role is a considered to be a super user role. This is a marker to indicate that it supersedes all other roles. Passport will attempt to enforce this contract when using the web UI, it is not enforced programmatically when using the API.

Example Response JSON
{
  "role": {
    "description": "a new role for the app",
    "id": "ce485a91-906f-4615-af75-81d37dc71e90",
    "name": "role 3",
    "isDefault": true
  }
}

8. Update an Application Role

This API is used to update an existing Application role. You must specify the Application Id and the role Id on the URI to identify the role that is being updated.

8.1. Request

Update an Application Role by Id

URI

PUT /api/application/{applicationId}/role/{roleId}

Table 22. Request Parameters

applicationId [UUID] Required

The Id of the Application.

roleId [UUID] Required

The Id of the role that is being updated.

Table 23. Request Body

role.description [String] Optional

A description for the role.

role.name [String] Required

The name of the Role.

role.isDefault [Boolean] Optional defaults to false

Whether or not the Role is a default role. A default role is automatically assigned to a user during registration if no roles are provided. More than one role can be marked as default.

role.isSuperRole [Boolean] Optional defaults to false Available Since 1.8.1

Whether or not the Role is a considered to be a super user role. This is a marker to indicate that it supersedes all other roles. Passport will attempt to enforce this contract when using the web UI, it is not enforced programmatically when using the API.

Example Request JSON
{
  "role": {
    "description": "a new role for the app",
    "name": "role 3",
    "isDefault": true
  }
}

8.2. Response

The response for this API contains the new information for the role that was updated.

Table 24. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

Table 25. Response Body

role.description [String]

The description of the role.

role.id [UUID]

The Id of the Role.

role.name [String]

The name of the Role.

role.isDefault [Boolean]

Whether or not the Role is a default role. A default role is automatically assigned to a user during registration if no roles are provided.

role.isSuperRole [Boolean] Available Since 1.8.1

Whether or not the Role is a considered to be a super user role. This is a marker to indicate that it supersedes all other roles. Passport will attempt to enforce this contract when using the web UI, it is not enforced programmatically when using the API.

Example Response JSON
{
  "role": {
    "description": "a new role for the app",
    "id": "ce485a91-906f-4615-af75-81d37dc71e90",
    "name": "role 3",
    "isDefault": true
  }
}

9. Delete an Application Role

This API is used to delete a role from an Application. You must specify the application Id and the role Id on the URI.

9.1. Request

Delete an Application Role by Id

URI

DELETE /api/application/{applicationId}/role/{roleId}

Table 26. Request Parameters

applicationId [UUID] Required

The Id of the Application the role belongs.

roleId [UUID] Required

The Id of the role to delete.

9.2. Response

This API does not return a JSON response body.

Table 27. Response Codes
Code Description

200

The request was successful. The response will be empty.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

404

The object you are trying to delete doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

10. Retrieve OAuth Configuration

Available Since Version 1.17.0.

This API is used to retrieve the Application OAuth configuration. When an API key is provided on the request the OAuth client secret will also be returned. When this API is called without authentication the client secret will not be returned in the response body.

10.1. Request

Retrieve the OAuth Configuration for an Application

URI

GET /api/application/{applicationId}/oauth-configuration

Table 28. Request Parameters

applicationId [UUID] Required

The Id of the Application to retrieve the OAuth configuration.

10.2. Response

Table 29. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

402

Your license has expired. The response will be empty. Contact sales@inversoft.com for assistance.

404

The object you requested doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the Passport log files. The response will be empty.

Table 30. Response Body

httpSessionMaxInactiveInterval Integer

The time in seconds until an inactive session will be invalidated. Used when creating a new session in the Passport Front End.

logoutURL String

The logout redirect URL when sending the user’s browser to the /oauth2/logout URI of the Passport Front End. This value is only used when a logout URL is not defined in your Application.

oauthConfiguration.authorizedRedirectURLs [Array<String>]

An array of URLs that are the authorized redirect URLs for Passport OAuth.

oauthConfiguration.clientId [String]

The OAuth client Id of the Application.

application.oauthConfiguration.clientSecret [String] Available Since 1.18.0

The OAuth client secret. This field will only be provided when the request was authenticated using an API key.

oauthConfiguration.logoutURL [String]

The logout URL for the Application. Passport will redirect to this URL after the user logs out of OAuth.

Example Response JSON
{
  "httpSessionMaxInactiveInterval": 3600,
  "logoutURL": "http://www.example.com/logout",
  "oauthConfiguration": {
    "authorizedRedirectURLs": [
      "http://www.example.com/oauth-callback"
    ],
    "clientId": "dfbd1210-2818-4353-adb2-952613eb5d96",
    "logoutURL": "http://www.example.com/logout"
  }
}