Azure API Management REST API Certificate entity (deprecated)

Warning

This page is deprecated.

Please refer to the documentation on accessing the Azure API Management REST API through Azure Resource Manager instead.

This topic describes how to manage certificates and their operations using the API Management REST API.

For more information about working with certificates in the publisher portal, see How to secure back-end services using mutual certificate authentication in Azure API Management.

For more information about working with the REST API, see the API Management .NET REST API Sample and the Getting Started with Azure API Management REST API video.

In this topic

Prerequisites

Important

Before making any calls into the API Management REST API, please review the API Management REST guide. This specifies the necessary authentication, version parameters, supported media types, and other information required in order to successfully call the API Management REST API.

Get a list of all certificates

This operation returns a collection of all certificates in the specified service instance.

Request

HTTP Method Relative Request URI
GET /certificates

Request Parameters

None.

Request Headers

None.

Request Body

None.

Query Parameters

Query Parameter Type Description
$filter string You can filter the results using OData filter expression syntax. The following fields and operators are supported

id:

- ge, le, eq, ne, gt, lt: substringof, startswith, endswith

subject:

- ge, le, eq, ne, gt, lt: substringof, startswith, endswith

thumbprint:

- ge, le, eq, ne, gt, lt: substringof, startswith, endswith

expirationDate:

- ge, le, eq, ne, gt, lt: N/A
$top string The number of entities to return.
$skip string The number of entities to skip.

Responses

200 OK

A Collection of the Certificate entities for the specified API Management service instance.

Sample response body
{  
  "value": [  
    {  
      "id": "/certificates/544fe9abc3b8f30fb490d90f",  
      "subject": "CN=myapi.cloudapp.net",  
      "thumbprint": "446581AC8386C0F79FE0C5C866431E45FCA5545E",  
      "expirationDate": "2016-08-21T21:10:42"  
    }  
  ],  
  "count": 1,  
  "nextLink": null  
}  

400 Bad Request

Request validation failed.

The response body contains an Error response representation.

Get a certificate

This operation returns the details of the certificate specified by its identifier.

Request

HTTP Method Relative Request URI
GET /certificates/{cid}

Request Parameters

Request Parameter Type Description
cid string Certificate identifier.

Responses

This operation has the following responses.

200 OK

The response headers contain the following metatada about the certificate.

Headers
ETag string Current entity state version. Should be treated as opaque and used to make conditional HTTP requests.

The response body contains the specified Certificate entity.

Sample response body
{  
  "id": "/certificates/544fe9abc3b8f30fb490d90f",  
  "subject": "CN=myapi.cloudapp.net",  
  "thumbprint": "446581AC8386C0F79FE0C5C866431E45FCA5545E",  
  "expirationDate": "2016-08-21T21:10:42"  
}  

400 Bad Request

Request validation failed.

The response body contains an Error response representation.

404 Not Found

The specified certificate does not exist.

The response body contains an Error response representation.

Get the metadata for a certificate

This operation returns the metadata for the certificate specified by its identifier.

Request

HTTP Method Relative Request URI
HEAD /certificates/{cid}

Request Parameters

Request Parameter Type Description
cid string Certificate identifier.

Responses

This operation has the following responses.

200 OK

The operation was successful.

Headers
ETag string Current entity state version. Should be treated as opaque and used to make conditional HTTP requests.

400 Bad Request

Request validation failed.

The response body contains an Error response representation.

404 Not found

The specified certificate does not exist.

Add or update a certificate

This operation adds a new certificate to or updates an existing certificate of the specified API Management service instance.

Request

HTTP Method Relative Request URI
PUT /certificates/{cid}

Request parameters

Request Parameter Type Description
cid string Certificate identifier. Must be unique in the current API Management service instance. Maximum length is 256 characters.

Request Headers

Request Header Description
If-Match The entity state version of the certificate. Required only if updating an existing certificate. A value of "*" can be used for If-Match to unconditionally apply the operation.

Request body

The request body is the following two properties from a Certificate entity.

{  
    data = "Base 64 encoded certificate using the application/x-pkcs12 representation",  
    password="..."  
}  

Note

Certificates must be in the .pfx format. Self-signed certificates are allowed.

The following code example shows how to specify a certificate as part of the request body.

public async Task UploadAsync(string filePath, string password, string certificateId, string sharedAccessSignature)  
{  
    const string apiVersion = "2014-02-14-preview"; // or other supported api-version  
    const string serviceName = "myservice";  
    var httpClient = new HttpClient();  
    string url = string.Concat("https://",  
        serviceName,  
        ".management.-azure-api.net/certificates/",  
        certificateId,  
        "?api-version=",  
        apiVersion,  
        "&password=",  
        password);  
  
    var request = new HttpRequestMessage(HttpMethod.Put, url);  
    request.Headers.Authorization = new AuthenticationHeaderValue("SharedAccessSignature", sharedAccessSignature);  
  
    // Create the body of the request in the following format  
    //{  
    //    data: "<Base64-encoded certificate>",  
    //    password: "<password here>"  
    //}  
  
    // Load the certificate and encode it to Base64.  
    var bytes = File.ReadAllBytes(filePath);  
    var encodedBytes = Convert.ToBase64String(bytes);  
  
    // Create the JSON body for the request.  
    var body = new JObject();  
    body.Add(new JProperty("data", encodedBytes));  
    body.Add(new JProperty("password", password));  
    request.Content = new StringContent(body.ToString());  
  
    // Make the request.  
    HttpResponseMessage response = await httpClient.SendAsync(request);  
  
    // Throw an exception if the call is not successful.  
    response.EnsureSuccessStatusCode();  
}  

Responses

This operation has the following responses.

201 Created

The new certificate was successfully added.

400 Bad Request

Request validation failed.

The response body contains an Error response representation.

409 Conflict

Certificate with the same identifier already exists.

The response body contains an Error response representation.

412 Precondition Failed

Returned if the resource doesn’t pass the condition specified by the If-Match header.

The response body contains an Error response representation.

Remove a certificate

This operation deletes the specified certificate.

Request

HTTP Method Relative Request URI
DELETE /certificates/{cid}

Request parameters

Request Parameter Type Description
cid string Certificate identifier.

Request Headers

Request Header Description
If-Match The entity state version of the certificate to remove. This header is required. A value of "*" can be used for If-Match to unconditionally apply the operation.

Responses

This operation has the following responses.

204 No Content

The certificate was successfully deleted.

400 Bad Request

Certificate cannot be deleted since it is being used by one or more policies.

The response body contains an Error response representation.

412 Precondition Failed

Returned if the resource doesn’t pass the condition specified by the If-Match header.

The response body contains an Error response representation.