Application version API

This allows the configuration of versions for mobile apps via a REST API. The Application version API offers the same functionality as the Admin interface and can be integrated in a Continuous Delivery (CD) environment.

Endpoints

All endpoints are protected via basic authentication, using the API client credentials. It requires an API client with the scope onegini_api_config (Config API).

Get a specific Application version

This returns the details of a specific Application version.

  • Endpoint: /api/v1/configuration/applications/{appId}/platforms/{platform}/versions/{versionName}/
  • Method: GET
  • Please note that / at the end is required

Path parameters:

Param Required Description
appId yes Unique identifier of the Application.
platform yes Platform for this Application version. Valid options are android and ios.
versionName yes Unique version name for this Application and platform.

Example request:

GET /api/v1/configuration/applications/myApp/platforms/ios/versions/1.1.0/ HTTP/1.1
Host: onegini.example.com
Content-Type: application/json

Example success response:

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "mobile_app_id": "ExampleApp",
   "platform": "ios",
   "version_name": "1.1.0",
   "status": "LOGIN_ONLY",
   "tampering_protection_enabled": false,
   "payload_encryption_enabled": true,
   "push_messaging_configuration_id": "f66d9bfc-7182-4c97-ae81-ddcd3f76a951",
   "use_apns_development_environment_enabled": true,
   "send_badge_number_enabled": true,
   "integrity_check": "FULL"
}

In the event of an error, one of the generic error codes will be returned.

List of Application versions per platform

This returns a list of all Application versions for a given platform.

  • Endpoint: /api/v1/configuration/applications/{appId}/platforms/{platform}/versions
  • Method: GET

Path parameters:

Param Required Description
appId yes Unique identifier of the Application.
platform yes Platform for this Application version. Valid options are android and ios.

Example request:

GET /api/v1/configuration/applications/myApp/platforms/ios/versions HTTP/1.1
Host: onegini.example.com
Content-Type: application/json

Example success response:

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "result": [
       {
           "mobile_app_id": "ExampleApp",
           "platform": "ios",
           "version_name": "1.1.0",
           "status": "LOGIN_ONLY",
           "tampering_protection_enabled": false,
           "payload_encryption_enabled": true,
           "push_messaging_configuration_id": "f66d9bfc-7182-4c97-ae81-ddcd3f76a951",
           "use_apns_development_environment_enabled": true,
           "send_badge_number_enabled": true,
           "integrity_check": "FULL"
       },
       {
           "mobile_app_id": "ExampleApp",
           "platform": "ios",
           "version_name": "1.10.0",
           "status": "LOGIN_REGISTRATION",
           "tampering_protection_enabled": false,
           "payload_encryption_enabled": true,
           "push_messaging_configuration_id": "c946a230-1567-4ff4-b182-2e2777ab0efa",
           "use_apns_development_environment_enabled": true,
           "send_badge_number_enabled": true,
           "application_bundle_identifier": "com.onegini.exampleapp",
           "integrity_check": "NONE"
       },
       {
           "mobile_app_id": "ExampleApp",
           "platform": "ios",
           "version_name": "1.11.0-nopush",
           "status": "LOGIN_REGISTRATION",
           "tampering_protection_enabled": false,
           "payload_encryption_enabled": true,
           "integrity_check": "FULL"
       }
  ]
}

In the event of an error, one of the generic error codes will be returned.

Create an Application version

This creates an Application version from scratch.

  • Endpoint: /api/v1/configuration/applications/{appId}/platforms/{platform}/versions
  • Method: POST

Path parameters:

Param Required Description
appId yes Unique identifier of the Application.
platform yes Platform for this Application version. Valid options are android and ios.

JSON body parameters:

Param Required Example Description
version_name yes 1.0.0 Unique version name for this Application and platform.
status yes LOGIN_ONLY Defines usage of this Application version. Values are DISABLED, LOGIN_ONLY and LOGIN_REGISTRATION.
application_​signature yes abdc Signature that is used to authenticate the Application version. Has restrictions when tampering protection is enabled. Not returned on GET.
tampering_​protection_​enabled no true Flag to enable tampering protection. Defaults to false.
payload_​encryption_​enabled no true Flag to enable payload encryption. Defaults to false.
push_​messaging_​configuration_​id no d10fe35f-ebb5-42bb-a81f-62a7034a68fb Unique identifier of the push messaging configuration for this Application version.
use_​apns_​development_​environment_​enabled no false For iOS only. When set to true the push messages will be sent to the APNS development environment.
send_​badge_​number_​enabled no true For iOS only. When set to true the number of unhandled push authentications are sent with the push request.
application_​bundle_​identifier depends com.example.myApp For iOS only. Unique identifier for an Application. Its value can be found in the Apple developer console. Required for iOS push messaging configurations created in Token Server 6.0.0 or later.
integrity_check no NONE Indicates if a full application integrity check is performed on mobile device. Available values are FULL and NONE. Default and recommended value is FULL.

Example request:

POST /api/v1/configuration/applications/myApp/platforms/ios/versions HTTP/1.1
Host: onegini.example.com
Content-Type: application/json

{
  "version_name": "1.0.0",
  "application_signature": "abdc",
  "tampering_protection_enabled": false,
  "payload_encryption_enabled": true,
  "status": "LOGIN_REGISTRATION",
  "push_messaging_configuration_id": "6727cf80-2807-11e6-b47f-89550f4d53bb",
  "use_apns_development_environment_enabled": false,
  "send_badge_number_enabled": true,
  "application_bundle_identifier": "com.example.myApp",
  "integrity_check": "FULL"
}

Example success response:

HTTP/1.1 201 CREATED
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Location: /api/v1/configuration/applications/myApp/platforms/ios/versions/1.1.0/

The success response body is empty.

In the event of an error, one of the generic error codes will be returned.

Clone an Application version

This creates a new Application version with values from an existing Application version. This can be useful when the new Application version needs the same settings for payload encryption, tampering protection or push configuration.

  • Endpoint: /api/v1/configuration/applications/{appId}/platforms/{platform}/versions/{originalVersionName}/clone
  • Method: POST

Path parameters:

Param Required Description
appId yes Unique identifier of the Application.
platform yes Platform for this Application version. Valid options are android and ios.
originalVersionName yes Unique version name for this Application and platform that is being cloned.

JSON body parameters:

Param Required Example Description
version_name yes 1.0.1 Unique version name for this Application and platform.
application_​signature yes abdc Signature that is used to authenticate the Application version. Has restrictions when tampering protection is enabled. Not returned on GET.
status no LOGIN_ONLY Defines usage of this Application version. Values are DISABLED, LOGIN_ONLY and LOGIN_REGISTRATION.

Example request:

POST /api/v1/configuration/applications/myApp/platforms/ios/versions/3.0.0/clone HTTP/1.1
Host: onegini.example.com
Content-Type: application/json

{
  "version_name": "3.0.1",
  "application_signature": "abdc",
  "status": "DISABLED"
}

Example success response:

HTTP/1.1 201 CREATED
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Location: /api/v1/configuration/applications/myApp/platforms/ios/versions/3.0.1/

The success response body is empty.

In the event of an error, one of the generic error codes will be returned.

Update an Application version

Some fields can be updated after creating an Application version.

  • Endpoint: /api/v1/configuration/applications/{appId}/platforms/{platform}/versions/{versionName}/
  • Request method: PATCH
  • Please note that / at the end is required

Path parameters:

Param Required Description
appId yes Unique identifier of the Application.
platform yes Platform for this Application version. Valid options are android and ios.
versionName yes Unique version name for this Application and platform.

JSON body parameters:

Only the fields that are sent in the request will be changed.

Param Required Example Description
application_​signature no abdc Signature that is used to authenticate the Application version. Has restrictions when tampering protection is enabled. If specified, it cannot be empty. Not returned on GET.
status no LOGIN_ONLY Defines usage of this Application version. Values are DISABLED, LOGIN_ONLY and LOGIN_REGISTRATION.
push_​messaging_​configuration_​id no d10fe35f-ebb5-42bb-a81f-62a7034a68fb Unique identifier of the push messaging configuration for this Application version. Use empty value to clear the field.
use_​apns_​development_​environment_​enabled no false For iOS only and requires a push messaging configuration to be set. When set to true the push messages will be sent to the APNS development environment.
send_​badge_​number_​enabled no true For iOS only and requires a push messaging configuration to be set. When set to true the number of unhandled push authentications are sent with the push request.
application_​bundle_​identifier depends com.example.myApp For iOS only and requires a push messaging configuration to be set. Unique identifier for an Application. Its value can be found in the Apple developer console. Required for iOS push messaging configurations created in Token Server 6.0.0 or later. Use empty value to clear the field.
integrity_check no NONE Indicates if a full application integrity check is performed on mobile device. Available values are FULL and NONE.

Example request:

PATCH /api/v1/configuration/applications/myApp/platforms/ios/versions/3.0.0/ HTTP/1.1
Host: onegini.example.com
Content-Type: application/json

{
  "application_signature": "123456789012345678901234567890AB",
  "status": "LOGIN_REGISTRATION"
}

Example success response:

HTTP/1.1 204 NO CONTENT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

The success response body is empty.

In the event of an error, one of the generic error codes will be returned.

Export an Application version config

This endpoint produces a ZIP file with the configuration that is needed by the Onegini SDK.

  • Endpoint: /api/v1/configuration/applications/{appId}/platforms/{platform}/versions/{versionName}/export
  • Method: GET

Path parameters:

Param Required Description
appId yes Unique identifier of the Application.
platform yes Platform for this Application version. Valid options are android and ios.
versionName yes Unique version name for this Application and platform.

Example Request:

GET /api/v1/configuration/applications/myApp/platforms/ios/versions/3.0.0/export HTTP/1.1
Host: onegini.example.com
application/zip;charset=UTF-8

Success response:

HTTP/1.1 200 
Content-Type: application/zip;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

The response body contains a ZIP file which is removed from the example for readability.

In the event of an error, one of the generic error codes will be returned.

Error codes

One of the following responses will be returned, containing a JSON object with an error code, a message and details about the error.

HTTP status Error code Message
400 invalid_request One or more parameters is missing or incorrect. The details contain the missing or incorrect parameters.
401 unauthorized Provide valid credentials to get access to the API.
403 forbidden Operation is not allowed for the current user.
404 not_found Mobile App, Platform, or Version cannot be found
409 conflict An application version with the same appId, platform, and version already exists.