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.
Authentication
All endpoints in the config API are secured by API client credentials.
It requires an API client with the onegini_api_config (config API) scope.
Endpoints
All endpoints are protected with the API client credentials (either client secret basic or private key JWT, depending on the client authentication method). 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
- The
/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" | (DEPRECATED, use application_signatures) Signature that is used to authenticate the application version. Has restrictions when tampering protection is enabled. Not returned on GET. |
| application_signatures | yes | ["abdc", "defg"] | Signatures that are used to authenticate the application version. Has restrictions when tampering protection is enabled. Not returned on GET. |
| 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. |
| 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. |
| framework | no | CORDOVA | For Android only. Set to CORDOVA when you send push messages to an Android app that is using Cordova. The actual push message will be sent via FCM for Cordova. |
| 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. |
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_signatures": ["abdc", "defg"],
"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 | no | "abdc" | DEPRECATED (use application_signatures) |
| application_signatures | no | ["abdc", "defg"] | Signatures that are used to authenticate the application version. Has restrictions when tampering protection is enabled. Not returned on GET. If not specified, all signatures are copied from the original version. |
| 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_signatures": ["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
- The
/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 |
|---|---|---|---|
| status | no | LOGIN_ONLY | Defines usage of this application version. Values are DISABLED, LOGIN_ONLY and LOGIN_REGISTRATION. |
| application_signatures | no | abdc" | (DEPRECATED, use application_signatures) Signature that is used to authenticate the application version. Has restrictions when tampering protection is enabled. Not returned on GET. |
| application_signatures | no | ["abdc", "defg"] | Signatures that ARE used to authenticate the application version. Has restrictions when tampering protection is enabled. If specified, it cannot be empty. Not returned on GET. |
| integrity_check | no | NONE | Indicates if a full application integrity check is performed on mobile device. Available values are FULL and NONE. |
| payload_encryption_enabled | no | true | Flag to enable payload encryption. It can be updated only if the Mobile SDK supports JWT authentication. |
| 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. |
| framework | no | CORDOVA | For Android only. Set to CORDOVA when you send push messages to an Android app that is using Cordova. The actual push message will be sent via FCM for Cordova. |
| 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. Use empty value to clear the field. |
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_signatures": ["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 Mobile 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. |
