# Certificates

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


## Add new certificate {#addcertificate}

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 ↓](#addcertificate-examples)

### `POST /certificates`

**Security:**

- [httpBasic]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-httpBasic)

**Request headers:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Api-Revision` | `string` | Required | 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]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#certificateobject)

**Responses**

**`201`** Returns the created certificate and new read only fields.

Response body:

**Content-Type:** `application/json`

[Certificate object]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#certificateobject)

**Examples**

*Example request*

```http
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"
}

```

*Response*

```http
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 {#getcertificate}

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

[Jump to examples ↓](#getcertificate-examples)

### `GET /certificates/{id}`

**Security:**

- [httpBasic]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-httpBasic)

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | `string` | Required | The ID of the certificate you want to perform operations against. |

**Request headers:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Api-Revision` | `string` | Required | The particular API revision you want to use. In general, this is `1.2`. Possible values: `1.2` |

**Responses**

**`200`** Returns information about the certificate specified in the request

Response body:

**Content-Type:** `application/json`

[Certificate object]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#certificateobject)

**Examples**

*Example request*

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

```

*Response*

```http
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 {#getcertificates}

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

[Jump to examples ↓](#getcertificates-examples)

### `GET /certificates`

**Security:**

- [httpBasic]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-httpBasic)

**Query parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `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:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Api-Revision` | `string` | Required | The particular API revision you want to use. In general, this is `1.2`. Possible values: `1.2` |
| `Content-Type` | `string` | Required | The request `Content-Type` must be `application/json; charset=utf-8`. Possible values: `application/json; charset=utf-8` |

**Responses**

**`200`** Returns an array of certificates.

Response body:

**Content-Type:** `application/json`

- **`certificates`** `array` <[Certificate object]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#certificateobject)>
- **`count`** `integer`

  The number of results on the current page.

- **`nextPage`** `string`

  The url for the next page of results.

  Format: `url`

- **`pagination`** `object` <[Pagination object]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#paginationobject)>

  Contains information about pagination, according to your query parameters.

**Examples**

*Example request*

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

```

*Response*

```http
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
    }
  ]                
}

```

*Response*

```http
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 {#removecertificate}

Removes a certificate from the system.

[Jump to examples ↓](#removecertificate-examples)

### `DELETE /certificates/{id}`

**Security:**

- [httpBasic]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-httpBasic)

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | `string` | Required | The ID of the certificate you want to perform operations against. |

**Request headers:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Api-Revision` | `string` | Required | The particular API revision you want to use. In general, this is `1.2`. Possible values: `1.2` |

**Responses**

**`204`** A successful request returns no content.

**Examples**

*Example request*

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

```

*Response*

```http
HTTP/1.1 204 No Content

```

---

## Update certificate {#updatecertificate}

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 ↓](#updatecertificate-examples)

### `PUT /certificates/{id}`

**Security:**

- [httpBasic]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-httpBasic)

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | `string` | Required | The ID of the certificate you want to perform operations against. |

**Request headers:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Api-Revision` | `string` | Required | 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]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#certificateobject)

**Responses**

**`200`** Returns the created certificate and new read only fields.

Response body:

**Content-Type:** `application/json`

[Certificate object]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#certificateobject)

**Examples**

*Example request*

```http
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>"
}

```

*Response*

```http
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
}

```

---