Make your first API call

9 minute read

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 token 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:

Access to DigiCert® Account Manager and the ability to create a service user.

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+.

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 token

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

Sign in to your account.
In the Manager menu (grid at top right), select Account.
In the Account menu, select Access > Service users.
Select Create service user.
Enter service user details:
1. Friendly name Enter a unique display name. The name must include only letters, numbers, spaces, dashes, and underscores. Actions are logged under this name.
2. Optional: Description Add additional information about the service user. This description only appears in the Service user details.
3. Optional: End date Specify an expiration date (UTC). For example, selecting January 12, 2026 means the service user expires at 23:59:59 UTC.
  Tip
  Update API integrations using this token ID before expiration to prevent disruptions. If needed, you can extend the expiration date later.
4. Email Provide the email address of the person managing this service user’s credentials. DigiCert ONE does not send emails to this address, so communicate any necessary details directly.
5. Accounts that can use this service user Select the accounts that can use this service user for their API integrations.
6. DigiCert ONE Manager access Assign one or more DigiCert ONE Managers. The service user can access the API for each assigned manager
Assign accounts and access:
- In the Accounts that can use this service user field, select the accounts this service user needs to interact with.
- In the DigiCert ONE Manager access field, assign one or more managers the service user will access via the API.
Select Next.
On the Roles and permissions page, select the user roles for each manager assigned to the service user.
Tip
Only assign roles necessary for the task or integration. If required, you can update these roles later.
Select Create service user.
In the Service user token ID window, copy the ID and save it securely.
Important
The token ID is displayed only once and cannot be recovered if lost.
After saving the token ID, select Close.

Once you have the API token, you’re ready to make authenticated API requests. Make sure you have the API token available to set the DC_API_TOKEN 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 token.

Include the API token 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 token 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 token 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 GET /user endpoint. This is a read-only request that returns a list of all sers for the account.

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 token for authentication. Replace <YOUR_API_TOKEN> with your service user’s API token.

export DC_API_TOKEN="<YOUR_API_TOKEN>"

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_TOKEN" \
-H "Accept: application/json" | jq '.'

Tip

If you would rather not use environment variables, replace $DC_BASE and $DC_API_TOKEN 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_TOKEN" Adds the API token 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.

If everything is set up correctly (valid base URL and API token), 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.

Add ?status=active to retrieve only active users:

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

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_TOKEN"
```

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_TOKEN"

Tip

Use the 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_TOKEN"

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_TOKEN"

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_TOKEN"

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 GET /user endpoint documentation for exact filter keys or date filters.

Was this page helpful?

Provide feedback

Need more help?

Account and platform

Certificates and PKI

Signing

Devices and IoT

Other resources

Make your first API call

Before you begin

Create a service user and get an API token

Tip

Tip

Important

Understand DigiCert ONE API basics

Note

Step 1: Build the GET request

Set environment variables

Send the request with cURL

Tip

Example response

Step 2: Add a query parameter

Tip

Step 3: Add multiple query parameters

Tip

Step 4: Explore other GET endpoints

Tip