---
title: "Make your first API call"
description: "Create credentials, send a test request, and explore common GET request patterns."
source_url: https://dev.digicert.com/get-started/make-your-first-api-call.html
---
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+.
> **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 token
If you don't already have a service user API token, follow these steps to create one in Account Manager:
1. Sign in to your account.
2. In the **Manager menu** (grid at top right), select **Account**.
3. In the Account menu, select **Access** > **Service users**.
4. Select **Create service user**.
5. 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
6. 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.
7. Select **Next**.
8. 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.
9. Select **Create service user**.
10. 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.
11. 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](#set-environment-variables)).
## 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.
> **Info**
>
> 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](/account-manager-api/api-reference.html#/operations/listAllUsers). This is a read-only request that returns a list of all users for the account.
The full API URL will be:
```text
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.
```bash
export DC_BASE="https://demo.one.digicert.com"
```
Next set your service user's API token for authentication. Replace `` with your service user's API token.
```bash
export DC_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).
```bash
curl -X 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:
```json
[
{
"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:
```bash
curl "$DC_BASE/account/api/v1/user?status=active" \
-H "x-api-key: $DC_API_TOKEN"
```
2. Change the status value to see different results. For example, use `?status=disabled` to retrieve only disabled users:
```bash
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*:
```bash
curl "$DC_BASE/account/api/v1/user?status=active&user_type=service" \
-H "x-api-key: $DC_API_TOKEN"
```
> **Tip**
>
> Use the [API reference](/account-manager-api/api-reference.html) 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:
```bash
curl "$DC_BASE/account/api/v1/organization" \
-H "x-api-key: $DC_API_TOKEN"
```
Example response:
```json
[
{
"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 `/role` (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):
```bash
curl "$DC_BASE/account/api/v1/role" \
-H "x-api-key: $DC_API_TOKEN"
```
Example response:
```json
{
"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 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:
```bash
curl "$DC_BASE/account/api/v1/audit-log?limit=10" \
-H "x-api-key: $DC_API_TOKEN"
```
Example response:
```json
{
"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 the [GET /audit-log endpoint](/account-manager-api/api-reference.html#/operations/listAuditLogs) documentation for supported filter keys and date filters.