REST API

Warning

This feature is still experimental, incomplete and will change without any advance notice.

django-ca provides an optional REST API based on Django Ninja. It allows you to list certificate authorities and certificates, as well as sign and revoke certificates. The API is available at the /api/ sub path. So if you installed django-ca at https://example.com/django-ca/, the API is available at https://example.com/django-ca/api/, with Open API documentation available at https://example.com/django-ca/api/docs/.

The API is disabled by default and depending how you installed django-ca, you might have to install additional dependencies manually.

Installation

The REST API requires the api extra to be installed.

For example, if you use django-ca as Django app, simply install it with:

$ pip install django-ca[api]

The Docker image already has everything installed, so you don’t need to take any extra steps if you use Docker or Docker Compose.

Enable the API

To enable the API, you need to set the CA_ENABLE_REST_API setting to True.

Authentication/Authorization

The API uses standard Django users with HTTP Basic Authentication for authentication and Django permissions are used for authorization.

The easiest way to add an API user is via the admin interface in the browser. Different permissions are required per endpoint:

Required permission

endpoints

Can view Certificate Authority

  • GET /api/ca/ - List available certificate authorities

  • GET /api/ca/{serial}/ - View certificate authority

Can change Certificate Authority

  • PUT /api/ca/{serial}/ - Update certificate authority

Can sign Certificate

POST /api/ca/{serial}/sign/ - Sign a certificate

Can view Certificate

  • GET /ca/{serial}/certs/ - List certificates

  • GET /ca/{serial}/certs/{certificate_serial}/ - View certificate

Can revoke Certificate

POST /ca/{serial}/revoke/{certificate_serial}/ - Revoke certificate

If you do not use the admin interface, Django unfortunately does not provide an out-of-the box command to create users, so you have to create them via manage.py shell with our small helper function create_api_user():

>>> from django_ca.api.utils import create_api_user
>>> create_api_user('api-username', password='api-password')

API documentation

You can always view the API documentation of your current django-ca version by viewing https://example.com/django-ca/api/docs/. You can also download the current openapi.json directly.

Below is the documentation for the current version (note that responses are currently not rendered due to this bug):

GET /django_ca/api/ca/

List available certificate authorities

Retrieve a list of currently usable certificate authorities.

Query Parameters:

  • expired (boolean) – Include expired CAs.

Status Codes:
GET /django_ca/api/ca/{serial}/

View certificate authority

Retrieve details of the certificate authority with the given serial.

Parameters:

  • serial (string) –

Status Codes:
PUT /django_ca/api/ca/{serial}/

Update certificate authority

Update a certificate authority.

All request body fields are optional, so you can also update only individual fields.

Parameters:

  • serial (string) –

Status Codes:
POST /django_ca/api/ca/{serial}/sign/

Sign a certificate

Sign a certificate.

The extensions value is completely optional and allows you to add additional extensions to the certificate. Usually extensions are defined either by the CA or by the named profile.

Parameters:

  • serial (string) –

Status Codes:
GET /django_ca/api/ca/{serial}/certs/

List certificates

Retrieve certificates signed by the certificate authority named by serial.

Parameters:

  • serial (string) –

Query Parameters:

  • autogenerated (boolean) – Include auto-generated certificates (e.g. OCSP responder certificates).

  • expired (boolean) – Include expired certificates.

  • profile (string) – Only return certificates generated with the given profile.

  • revoked (boolean) – Include revoked certificates.

Status Codes:
GET /django_ca/api/ca/{serial}/certs/{certificate_serial}/

View certificate

Retrieve details of the certificate with the given certificate serial.

Parameters:

  • serial (string) –

  • certificate_serial (string) –

Status Codes:
POST /django_ca/api/ca/{serial}/revoke/{certificate_serial}/

Revoke certificate

Revoke a certificate with the given serial.

Both reason and compromised fields are optional.

Parameters:

  • serial (string) –

  • certificate_serial (string) –

Status Codes:

Utility functions

django_ca.api.utils.create_api_user(username: str, password: str, view_certificateauthority: bool = True, change_certificateauthority: bool = True, sign_certificate: bool = True, view_certificate: bool = True, revoke_certificate: bool = True, **extra_fields: Any) → User[source]

Create an API user capable of using the REST API.

By default, the user will be able to perform all actions provided by the API.

Note that unlike create_user(), the password argument is the second argument and mandatory. You can still pass an email address as keyword argument.

>>> create_api_user("username", "password", revoke_certificate=False, email="user@example.com")
Parameters:
usernamestr

The username for the API user.

passwordstr

The password for the API user.

view_certificateauthoritybool, optional

If the user is able to list/view certificate authorities via the API.

change_certificateauthoritybool, optional

If the user is able to update certificate authorities via the API.

sign_certificatebool, optional

If the user is able to sign new certificates via the API.

view_certificatebool, optional

If the user is able to list/view existing certificates via the API.

revoke_certificatebool, optional

If the user is able to revoke certificates via the API.

**extra_fields

Any additional keyword arguments are passed to create_user().