GET /rest/v1/certificates

Implementation notes

Handles the GET request of retrieving all certificates within Bosch IoT Rollouts. Required permission: READ_CERTIFICATE

Get paged list of certificates

CURL

$ curl 'https://management-api.host.com/rest/v1/certificates?offset=0&limit=2&sort=commonName%3ADESC' -i -X GET

Request URL

A GET request is used to access the certificate collection

GET /rest/v1/certificates?offset=0&limit=2&sort=commonName%3ADESC HTTP/1.1
Host: management-api.host.com

Request query parameter

Parameter Description

limit

The maximum number of entries in a page (default is 50).

sort

The query parameter sort allows to define the sort order for the result of a query. A sort criteria consists of the name of a field and the sort direction (ASC for ascending and DESC descending). The sequence of the sort criteria (multiple can be used) defines the sort order of the entities in the result.

offset

The paging offset (default is 0).

Request parameter example

GET /rest/v1/certificates?offset=0&limit=2&sort=commonName%3ADESC HTTP/1.1
Host: management-api.host.com

Response (Status 200)

Response fields

Path Type Description Allowed Values

total

Number

Total number of elements

size

Number

Current page size

content

Array

List of certificates

content[].id

Number

The technical identifier of the certificate

content[].keyId

Number

The technical identifier of the (certified) asymmetric key

content[].commonName

String

The common name of the certificate

content[]._links.revoke.href

String

Link to revoke the certificate via HTTP POST

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 361

{
  "content" : [ {
    "commonName" : "rollouts-sample-cert",
    "keyId" : 2,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/certificates/2"
      },
      "revoke" : {
        "href" : "https://management-api.host.com/rest/v1/certificates/2/revoke"
      }
    },
    "id" : 2
  } ],
  "total" : 1,
  "size" : 1
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

POST /rest/v1/certificates

Implementation Notes

Handles the POST request to issue a new certificate within Bosch IoT Rollouts. Required Permission: CREATE_CERTIFICATE

Issue certificate

CURL

$ curl 'https://management-api.host.com/rest/v1/certificates' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "signingAlgorithm" : "SHA512_WITH_RSA",
  "caId" : "77a82d47-b22f-4492-85e3-6807e4c27322",
  "keyId" : 3,
  "distinguishedName" : {
    "country" : "DE",
    "commonName" : "rollouts-sample-cert",
    "stateOrProvince" : "Brandenburg",
    "organization" : "Bosch.IO GmbH",
    "localityOrCity" : "Berlin",
    "organizationUnit" : "Bosch IoT Rollouts"
  },
  "validity" : "P1Y",
  "validityNotBefore" : "2023-08-03T12:31:16.281222093Z"
}'

Request URL

POST /rest/v1/certificates HTTP/1.1
Content-Type: application/json
Content-Length: 442
Host: management-api.host.com

{
  "signingAlgorithm" : "SHA512_WITH_RSA",
  "caId" : "77a82d47-b22f-4492-85e3-6807e4c27322",
  "keyId" : 3,
  "distinguishedName" : {
    "country" : "DE",
    "commonName" : "rollouts-sample-cert",
    "stateOrProvince" : "Brandenburg",
    "organization" : "Bosch.IO GmbH",
    "localityOrCity" : "Berlin",
    "organizationUnit" : "Bosch IoT Rollouts"
  },
  "validity" : "P1Y",
  "validityNotBefore" : "2023-08-03T12:31:16.281222093Z"
}

Request fields

Path Type Description Allowed Values Mandatory

caId

String

The ID of the certificate authority (CA) that shall be used to issue the new certificate.

X

keyId

Number

The technical identifier of the key that shall be certified.

X

signingAlgorithm

String

The signing algorithm that shall be used for the certifiation. The specified algorithm needs to be supported by the specified CA.

[SHA256_WITH_ECDSA, SHA384_WITH_ECDSA, SHA512_WITH_ECDSA, SHA256_WITH_RSA, SHA384_WITH_RSA, SHA512_WITH_RSA]

X

validity

String

The validity of the new certificate specified as a ISO-8601 duration (format 'P(n)Y(n)M(n)D'), e.g. 'P1Y'

X

validityNotBefore

String

The point in time in ISO-8601 format, the certificate becomes valid, e.g. '2022-04-02T08:30:00.000Z'

distinguishedName

Object

The distinguished name of the certificate to be issued.

X

distinguishedName.commonName

String

The common name of the new certificate.

X

distinguishedName.country

String

The (two-letter) country code.

distinguishedName.stateOrProvince

String

State or province.

distinguishedName.localityOrCity

String

Locality or city.

distinguishedName.organization

String

Organization.

distinguishedName.organizationUnit

String

Organization unit.

Response (Status 201)

Response fields

Path Type Description Allowed Values

id

Number

The technical identifier of the new certificate

keyId

Number

The technical identifier of the certified key

commonName

String

The common name of the new certificate

certificate

String

The base64-encoded certificate

certificateChain

String

The base64-encoded certificate chain (excluding the end-entity certificate)

_links.revoke.href

String

Link to revoke the certificate via HTTP POST.

Response example

HTTP/1.1 201 Created
Content-Type: application/hal+json
Content-Length: 495

{
  "commonName" : "rollouts-sample-cert",
  "keyId" : 3,
  "certificate" : "-----BEGIN CERTIFICATE----- base64-encoded certificate -----END CERTIFICATE-----",
  "certificateChain" : "-----BEGIN CERTIFICATE----- base64-encoded certificate -----END CERTIFICATE-----",
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/certificates/3"
    },
    "revoke" : {
      "href" : "https://management-api.host.com/rest/v1/certificates/3/revoke"
    }
  },
  "id" : 3
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, data volume restriction applies or quota limit exceeded.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request.

See Error body

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/certificates/{certificateId}

Implementation Notes

Handles the GET request of retrieving a specific certificate from Bosch IoT Rollouts. Required Permission: READ_CERTIFICATE

Get single certificate

CURL

$ curl 'https://management-api.host.com/rest/v1/certificates/4' -i -X GET

Request URL

GET /rest/v1/certificates/4 HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

certificateId

The technical identifier of the (end-entity) certificate

Response (Status 200)

Response fields

Path Type Description Allowed Values

id

Number

The technical identifier of the certificate

keyId

Number

The technical identifier of the (certified) asymmetric key

commonName

String

The common name of the certificate

certificate

String

The base64-encoded certificate

certificateChain

String

The base64-encoded certificate chain (excluding the end-entity certificate)

_links.revoke.href

String

Link to revoke the certificate via HTTP POST.

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 495

{
  "commonName" : "rollouts-sample-cert",
  "keyId" : 4,
  "certificate" : "-----BEGIN CERTIFICATE----- base64-encoded certificate -----END CERTIFICATE-----",
  "certificateChain" : "-----BEGIN CERTIFICATE----- base64-encoded certificate -----END CERTIFICATE-----",
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/certificates/4"
    },
    "revoke" : {
      "href" : "https://management-api.host.com/rest/v1/certificates/4/revoke"
    }
  },
  "id" : 4
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Target.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

POST /rest/v1/certificates/{certificateId}/revoke

Implementation Notes

Handles the POST request to revoke a certificate. Required Permission: DELETE_CERTIFICATE

Revoke a certificate

Curl

$ curl 'https://management-api.host.com/rest/v1/certificates/1/revoke' -i -X POST

Request URL

POST /rest/v1/certificates/1/revoke HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

certificateId

The technical identifier of the (end-entity) certificate to be revoked.

Response (Status 204)

Response example

HTTP/1.1 204 No Content

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Target.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request.

See Error body

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

Additional content

Error body

{
  "errorCode": "string",
  "exceptionClass": "string",
  "message": "string",
  "parameters": [
    "string"
  ]
}

Field description

Field

Description

errorCode

A error code/key set by server

exceptionClass

The involved exceptionClass

message

An error message set by the server

parameters

A list of parameters

© Bosch.IO GmbH, all rights reserved Corporate information | Data protection notice | Legal information | Support | Free plans