Certificates

These endpoints supports Apple certificates only. Google certificates can be managed via the UI.

Add new certificate

Adds a new Apple Wallet certificate to the Wallet system. If the specified certificate exists in our system, and the baseName and teamIdentifier match the existing certificate, we will renew/update the existing certificate.

When adding a certificate, you must paste the contents of your p12 certificate into the certificate field in the request payload. You can get the contents of your p12 file with the two following commands:

openssl base64 -in wallet-prod.p12 -out wallet-prod.pem
cat wallet-prod.pem | tr -d "\n\r" | less

The response contains the ID of your new certificate. You will use the ID to perform subsequent actions (GET, PUT, or DELETE) against this certificate. The response will also contain other information gathered from the certificate. You can find information about these additional fields under Get Certificate.

Jump to examples ↓

POST /certificates

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Request body:

Content-Type: application/json
Certificate object

Responses

201
Returns the created certificate and new read only fields.
Response body:
- Content-Type: application/json
  Certificate object

Examples

POST /v1/certificates HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2

{
    "vendor": "Apple",
    "name": "editable name",
    "certificate": "NTUtNDc2Ni1hMzI4LWEwOGU3YWI2ZDk3Mg==",
    "comment": "something about this cert",
    "enabled": true,
    "default": false,
    "password": "secret"
}

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "40adce15-5c52-479d-8620-54c21cd851a6",
    "vendor": "Apple",
    "name": "editable name",
    "baseName": "internal cert name",
    "comment": "something about this cert",
    "teamIdentifier": "XYZ",
    "enabled": true,
    "default": false,
    "createdAt": "2016-05-26T23:23:21Z",
    "updatedAt": "2016-05-26T22:23:21Z",
}

Get certificate

Returns information about a certificate, including an array of templates that use the certificate.

Jump to examples ↓

GET /certificates/{id}

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

id stringREQUIRED
The ID of the certificate you want to perform operations against.

Responses

200
Returns information about the certificate specified in the request
Response body:
- Content-Type: application/json
  Certificate object

Examples

GET /v1/certificates/9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9",
  "vendor": "Apple",
  "baseName": "pass.com.company.sample.alpha",
  "teamIdentifier": "PGJV57GD94",
  "nfcSupport": true,
  "enabled": true,
  "default": false,
  "createdAt": "2022-04-05T03:22:47.000Z",
  "updatedAt": "2022-04-05T03:22:47.000Z",
  "validityStart": "2021-11-03T03:45:53.000Z",
  "validityEnd": "2022-12-03T04:45:52.000Z",
  "expired": true
}

List certificates

Returns a list of certificates, including an array of templates that use the certificate.

Jump to examples ↓

GET /certificates

Query parameters:

vendor string
The vendor of certificate you want to return.
Possible values: Apple
enabled boolean
Indicates whether or not the certificate is enabled.
order string
Indicates the field to order results by.
page integer
Indicates the page of results to return.
pageSize integer
Indicates the number of results per page.
direction string
Indicates the direction in which to return results.
Possible values: ASC, DESC

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2
Content-Type stringREQUIRED
Possible values: application/json; charset=utf-8

Responses

200
Returns an array of certificates.
Response body:
- Content-Type: application/json
  OBJECT PROPERTIES
  - certificates array
  - count integer
    The number of results on the current page.
  - nextPage string
    The url for the next page of results.
  - pagination object<Pagination object>
    Contains information about pagination, according to your query parameters.

Examples

GET /v1/certificates HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "certificates": [
    {
    "id": "9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9",
    "vendor": "Apple",
    "baseName": "pass.com.company.sample.alpha",
    "teamIdentifier": "PGJV57GD94",
    "nfcSupport": true,
    "enabled": true,
    "default": false,
    "createdAt": "2022-04-05T03:22:47.000Z",
    "updatedAt": "2022-04-05T03:22:47.000Z",
    "validityEnd": "2022-12-03T04:45:52.000Z",
    "validityStart": "2021-11-03T03:45:53.000Z",
    "expired": true
    }
  ]                
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "nextPage": "https://wallet.urbanairship.com/v1/certificates/list/?page=11&pageSize=10",
    "count": 2,
    "pagination": {
        "order": "name",
        "page": 1,
        "start": 0,
        "direction": "DESC",
        "pageSize": 10
    },
    "certificates":[
        {
            "id": "40adce15-5c52-479d-8620-54c21cd851a6",
            "vendor": "Apple",
            "baseName": "pass.com.myName.test",
            "name": "editable name",
            "comment": "something about this cert",
            "teamIdentifier": "9M8MY376H5",
            "nfcSupport": false,
            "enabled": false,
            "createdAt": "2018-05-26T23:23:21Z",
            "updatedAt": "2019-05-26T22:23:21Z",
            "expired": false,
            "validityStart": "2018-05-26T23:45:00Z",
            "validityEnd": "2019-05-26T23:45:00Z",
            "templates": [
                {"id": 123,"name": "templateName1"},
                {"id": 221,"name": "templateName2"}
            ]
        },
        {
            "id": "12adce15-5c52-479d-8620-54c21cd851aa",
            "vendor": "Apple",
            "baseName", "pass.wallet.myName.anotherTest",
            "name": "editable name1",
            "comment": "a plain text description of this cert",
            "teamIdentifier": "OGKV57GD95",
            "nfcSupport": true,
            "enabled": false,
            "default": false,
            "createdAt": "2018-04-26T23:23:21Z",
            "updatedAt": "2019-04-27T17:22:00Z",
            "expired": false,
            "validityStart": "2018-05-26T23:45:00Z",
            "validityEnd": "2019-05-26T23:45:00Z",
            "templates": [
                {"id": 123, "name": "templateName1"},
                {"id": 221, "name": "templateName2"}
            ]
        }
    ]
}

Remove certificate

Removes a certificate from the system.

Jump to examples ↓

DELETE /certificates/{id}

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

id stringREQUIRED
The ID of the certificate you want to perform operations against.

Responses

204
A successful request returns no content.

Examples

DELETE /v1/certificates/9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

HTTP/1.1 204 No Content

Update certificate

Updates a certificate. Note the following behaviors:

The following fields can be updated directly: enabled, default, comment, and name.
If fields enabled and default are not specified they won’t be changed.
If fields comment and name are not specified, we assume the value needs to be removed. If you don’t want to change the value, specify null values.
Some of the fields will be extracted from the certificate and will be updated indirectly: teamIdentifier and baseName.
The field updatedAt will change with each update.
The field createdAt cannot be changed.
If the user specifies an invalid id in the path or no certificate can be found we will return an error (see below).
Changing the default certificate is done by setting the new certificate "default": true.
A single certificate must be set as the default. You cannot set the current default certificate to "default": false.

Jump to examples ↓

PUT /certificates/{id}

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

id stringREQUIRED
The ID of the certificate you want to perform operations against.

Request body:

Content-Type: application/json
Certificate object

Responses

200
Returns the created certificate and new read only fields.
Response body:
- Content-Type: application/json
  Certificate object

Examples

PUT /v1/certificates/9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2

{
  "certificate": "<Certificate PEM BASE94 content goes here>"
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9",
  "vendor": "Apple",
  "baseName": "pass.com.urbanairship.sample.alpha",
  "teamIdentifier": "PGJV57GD94",
  "nfcSupport": true,
  "enabled": true,
  "createdAt": "2022-04-05T03:22:47.000Z",
  "updatedAt": "2024-02-06T19:01:37.415Z",
  "validityStart": "2022-12-02T22:39:50.000Z",
  "validityEnd": "2024-01-01T22:39:49.000Z",
  "expired": true
}