Skip to main content

Make your first API call

This guide walks you through making your first DigiCert® ONE API call using the Account Manager API. We will focus on GET requests, using an API key for authentication, and the demo environment (demo.one.digicert.com) by default.

Before you begin

Before making your first API call, make sure you have the following:

  • Service user with an API Key. You will be using an API key to authenticate. Make sure this service user has Account Manager access with read permissions.

  • Basic API tools and libraries for making HTTP requests:

    • Command line: cURL (and optionally jq for formatting JSON output).

    • Programming languages: A recent runtime for your preferred language, such as Python 3, Node.js 18+, or Java 11+.

Note

For production, you would use https://one.digicert.com as the base URL. We'll use the demo environment in this guide. Remember, demo credentials do not work in production.

Create a service user and get an API key

If you don't already have a service user API key, follow these steps to create one in Account Manager:

Once you have the API key, you're ready to make authenticated API requests. Make sure you have the API key available to set the DC_API_KEY environment variable (as shown below).

Understand DigiCert ONE API basics

Before diving into code, it's important to understand how DigiCert ONE APIs are structured and secured.

Base URL structure

All DigiCert ONE APIs share a common URL pattern:

https://{hostname}/{product}/api/v{n}/{resource}

Putting it together, a typical Account Manager API endpoint in demo might look like:

https://demo.one.digicert.com/account/api/v1/user

Authentication

DigiCert ONE uses secure, header-based authentication. In most cases (especially for server-to-server integrations or CI/CD), you will use an API key.

Include the API key value in an x-api-key HTTP header on every request. Each API call is made over HTTPS and uses JSON for request and response bodies.

Note

While mutual TLS (mTLS) authentication with a client certificate is supported, this guide uses an API key to keep things straightforward.

Demo vs. production

DigiCert ONE provides separate environments for testing (demo) and production across regions.

Always start with the demo environment for initial development and testing. When you move to production, you will create a new service user and API key in the production environment and simply change the base URL to the production {hostname}. The rest of the path remains the same.

With these basics in mind, it's time to make your first DigiCert ONE API call.

Step 1: Build the GET request

For your first call, we'll retrieve a list of users in your account using Account Manager GET /user endpoint. This is a read-only request that returns the account's user list.

The full API URL will be:

https://demo.one.digicert.com/account/api/v1/user

Let's construct and send this request.

Set environment variables

First, we'll store the base URL (hostname) for DigiCert ONE API requests. Use the demo environment for testing:

export DC_BASE="https://demo.one.digicert.com"

Next set your service user's API key for authentication. Replace <YOUR_API_KEY> with your service user's API key.

export DC_API_KEY="<YOUR_API_KEY>"

Send the request with cURL

Using cURL in a shell is a quick way to test the API call. We'll include the x-api-key header for authentication and request JSON output. For readability, we also pipe the output to jq (a JSON formatter):

curl GET "$DC_BASE/account/api/v1/user" \
-H "x-api-key: $DC_API_KEY" \
-H "Accept: application/json" | jq

Tip

If you’d rather not use environment variables, replace $DC_BASE and $DC_API_KEY with their literal values.

Command breakdown:

  • $DC_BASE/account/api/v1/user The full URL (base URL + path). If you followed the prerequisites, $DC_BASE is set to https://demo.one.digicert.com.

  • -H "x-api-key: $DC_API_KEY" Adds the API key in the header for authentication.

  • -H "Accept: application/json" (Optional) Explicitly tells the server we expect JSON response. DigiCert ONE APIs use JSON by default.

  • | jq (Optional) The response is piped to jq to pretty-print the JSON.

If everything is set up correctly (valid base URL and API key), you should receive a JSON response listing all users the service user is permitted to view.

Example response

A successful response from the /user endpoint will return HTTP 200 OK with a JSON body containing a list of users. The JSON has a pagination section and an array of user objects. For example, you might see:

[
  {
    "id": "783a6a45-b74b-4635-bb4b-69855910ccd3",
    "email": "jane@example.com",
    "status": "ACTIVE",
    "access_scope": "account",
    "primary_account_id": "130deba5-3ebb-43b2-8183-1a9940d460f5",
    "created_at": "2021-06-23T08:55:19Z",
    "created_by": "8f7f8b1f-63c1-4580-af7d-ea4cd890e8f7",
    "user_type": "service",
    "friendly_name": "Example service user",
    "description": "",
    "locale": "en_US",
    "applications": [
      {
        "id": "2d3a72fd-ad44-4a9b-952a-2bcadb14a741",
        "name": "Trust Lifecycle",
        "permissions": [
          "VIEW_EM_SEAT",
          "VIEW_EM_AUDIT_LOG",
          "VIEW_EM_CERTIFICATE",
          "VIEW_EM_PROFILE"
        ]
      },
      {
        "id": "1a05282a-ec70-4da9-b921-933c070fcf80",
        "name": "IoT Trust",
        "permissions": [
          "VIEW_IOT_CERTIFICATE",
          "VIEW_IOT_ENROLLMENT_PROFILE"
        ]
      },
      {
        "id": "97b97f1b-8d1d-4203-a62c-0a209a1bea0a",
        "name": "Document Trust",
        "permissions": [
          "MANAGE_DSM_VIEW_CERTIFICATE_PROFILES",
          "MANAGE_DSM_ADD_VALIDATIONS",
          "MANAGE_DSM_VIEW_CERTIFICATE_TEMPLATES",
          "MANAGE_DSM_VIEW_VALIDATIONS"
        ]
      },
      {
        "id": "78c0355a-e1ca-4978-b60c-e9d66b9e1f30",
        "name": "Account Manager",
        "permissions": [
          "MANAGE_AM_ACCOUNT",
          "VIEW_AM_AUDIT_LOG"
        ]
      },
      {
        "id": "fd2b688d-43bd-4b4a-9fd6-f883ad9e813d",
        "name": "CA Manager",
        "permissions": [
          "VIEW_CM_LICENSE"
        ]
      },
      {
        "id": "7660bdb3-66e7-46e6-928f-dcae4d64ee91",
        "name": "Software Trust",
        "permissions": [
          "MANAGE_SM_CERTIFICATE_PROFILE",
          "VIEW_SM_CERTIFICATE",
          "SIGN_SM_HASH"
        ]
      }
    ],
    "accounts": [
      {
        "id": "4b13f12d-c8b2-4c49-a21f-9b399364f2ce",
        "name": "Example account",
        "active": true,
        "service_period": {
          "from": "2021-05-06",
          "to": "2030-05-06"
        },
        "friendly_identifier": "1234567",
        "locale": "en_US"
      }
    ]
  }
]

Congratulations! You just made your first DigiCert ONE API call.

Next, we'll explore common API usage patterns like query parameters, filtering, error handling, and other GET endpoints.

Step 2: Add a query parameter

If your account has a lot of users, it can be helpful to limit the returned results using a query parameter. The status parameter allows you to filter results based on user status.

  1. Add ?status=active to retrieve only active users:

    curl "$DC_BASE/account/api/v1/user?status=active" \
  -H "x-api-key: $DC_API_KEY"

  2. Change the status value to see different results. For example, use ?status=disabled to retrieve only disabled users:

    curl "$DC_BASE/account/api/v1/user?status=disabled" \
  -H "x-api-key: $DC_API_KEY"

Tip

When implementing in code, consider caching results if you need to frequently access the same filtered data, as each call returns the complete filtered set.

Step 3: Add multiple query parameters

You can filter results using multiple categories. For example, you can filter to fetch only users that are active and a service user. Using multiple query parameters helps you narrow down data without retrieving everything.

For instance, a GET to the Account Manager /user endpoint supports status, account_id, user_type, user_name, and email parameters. To use multiple filters, combine each additional parameter after the first with an &.

The following returns all service users that have a status of active:

curl "$DC_BASE/account/api/v1/user?status=active&user_type=service" \
  -H "x-api-key: $DC_API_KEY"

Tip

Use the Account Manager API reference to discover available query parameters for each endpoint. Keep in mind that endpoints do not always support the same parameters, for example pagination and filters like account_id and email might not be available on all endpoints.

Step 4: Explore other GET endpoints

So far, we focused on /user. Account Manager API provides other useful GET endpoints. The usage pattern (base URL + path, with x-api-key header) is the same for all. Here are a few key endpoints with examples.

GET /organization (list organizations)

To list all organizations your account can access:

curl "$DC_BASE/account/api/v1/organization" \
  -H "x-api-key: $DC_API_KEY"

Example response:

[
  {
    "id": "d9674d8f-7ad6-4280-89b5-136c2aded288",
    "name": "DigiCert Inc.",
    "address": "2801 N Thanksgiving Way",
    "address2": "Suite 500",
    "zip_code": 84043,
    "city": "Lehi",
    "state": "Utah",
    "country": "US",
    "phone": "+1 (123) 456-7890",
    "account": {
      "id": "ff94b6dc-d360-4245-9918-0d0cf7ac347a",
      "name": "Example Account"
    },
    "active": true
  }
]

Each organization has an id, a name, a status (active), and possibly an account association. You can use query parameters (such as limit/offset and account_id) here as well if you have many organizations.

GET /roles (list user roles)

Roles define sets of permissions that can be assigned to users. To fetch the available roles in your account (for the products you have access to):

curl "$DC_BASE/account/api/v1/role" \
  -H "x-api-key: $DC_API_KEY"

Example response:

{
  "ca_manager": [
    {
      "name": "CM_PKI_MANAGER",
      "display_name": "CM PKI MANAGER",
      "description": "Role with CM view permissions",
      "type": "default",
      "status": "ACTIVE",
      "access_scope": "account"
    },
    {
      "name": "CM_KEY_ESCROW",
      "display_name": "Key Escrow",
      "description": "CM Key Escrow",
      "type": "default",
      "status": "ACTIVE",
      "access_scope": "account"
    }
  ],
  "account_manager": [
    {
      "name": "AM_ACCOUNT_ADMIN",
      "display_name": "AM ACCOUNT ADMIN",
      "description": "Admin role with view and manage permissions",
      "type": "default",
      "status": "ACTIVE",
      "access_scope": "account"
    },
    {
      "name": "AM_DEFAULT_USER",
      "display_name": "AM DEFAULT USER",
      "description": "Default role with view permissions",
      "type": "default",
      "status": "ACTIVE",
      "access_scope": "account"
    },
    {
      "name": "AM_ACCOUNT_USER",
      "display_name": "AM ACCOUNT USER",
      "description": "Role with view permissions",
      "type": "default",
      "status": "ACTIVE",
      "access_scope": "account"
    },
    {
      "name": "AM_ACCOUNT_MANAGER",
      "display_name": "Account manager",
      "description": "AM Account manager",
      "type": "default",
      "status": "ACTIVE",
      "access_scope": "account"
    },
    {
      "name": "AM_USER_MANAGER",
      "display_name": "User manager",
      "description": "AM User manager",
      "type": "default",
      "status": "ACTIVE",
      "access_scope": "account"
    },
    {
      "name": "AM_VIEW_ONLY",
      "display_name": "View only",
      "description": "AM View only",
      "type": "default",
      "status": "ACTIVE",
      "access_scope": "account"
    }
  ],
 // ... other managers ...
}

Each role includes a a name, display name, description, as well as access scope. Use this endpoint to see what roles exist or to get role names programmatically.

GET /audit-log (list audit events)

The audit log records actions taken in Account Manager. For example, user creation, role changes, and login attempts. To fetch audit log entries:

curl "$DC_BASE/account/api/v1/audit-log?limit=10" \
  -H "x-api-key: $DC_API_KEY"

Example response:

{
  "total": 100,
  "offset": 0,
  "limit": 10,
  "items": [
    {
      "id": "90edebb0-e706-4d09-bdfc-1b6a5917e7c5",
      "account": {
        "id": "88dd63d3-af43-4517-8222-70511968aed8",
        "name": "Example Account"
      },
      "resource_type": "user",
      "resource_id": "62646824-9462-42f2-b061-c43bb6f19cf3",
      "resource_name": "john.doe",
      "action": "create",
      "user": {
        "id": "8384e9e5-2eb5-42d8-8615-218a97237143",
        "name": "jane.doe"
      },
      "timestamp": "2023-05-26T17:09:30Z",
      "description": "User has been created by api",
      "status": "success"
    }
    // ... additional events ...
  ]
}

Each audit log entry includes an id, a timestamp, the actor (user or service user who performed the action), the action type, the target (object affected), and the result/status.

Tip

You can use query parameters to filter audit logs, such as by date range or action type. See Account Manager GET /user endpoint documentation for exact filter keys or date filters.

In this section: