> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/feature-management-experimentation/management-and-administration/api-keys.md).

# API Keys

The Harness platform supports multiple types of API keys and tokens, including personal access tokens (PATs), service account API keys, and SDK API keys. The following section focuses on creating and using SDK API keys.

You typically create one client-side and one server-side SDK API key per environment in Harness FME. While multiple keys of the same type are supported, [Harness FME SDKs](/feature-management-experimentation/new-to-fme/sdks-and-customer-deployed-components.md) must use the matching key type; client-side for frontend and mobile SDKs, and server-side for backend SDKs.

To create an SDK API key in Harness FME:

1. From the FME navigation menu, click **FME Settings** and select **Projects**.
2. Click **View** under the **Actions** column for the project you want to create an SDK API key in.

   ![](/files/bfH8ZVHeWayOe7cjpYQi)
3. Click **Create SDK API Key** on the **SDK API Keys** tab.

   ![](/files/KAy8ojhgJUmx15HFHw6Z)
4. Enter a name for the SDK API key.
5. Select the type of SDK API key: **Client-side** or **Server-side**.
6. Select an environment from the dropdown menu in the `Environments` section.
7. Click **Create API key**.

{% hint style="info" %}
The following sections provides general information about Harness API keys, personal access tokens (PATs), and service accounts. This content applies across the Harness platform and is included here for reference.
{% endhint %}

Harness APIs use API keys to authenticate requests. You can create API keys for either your personal account or a [service account](/harness-ai/use-harness-platform/platform-access-control/add-and-manage-service-account.md). API keys for personal accounts can be created only at the account level, whereas service account API keys can be created at any [scope](https://github.com/iKettles/harness-gitbook/tree/main/platform-access-control.md#permissions-hierarchy-scopes).

After creating an API key, you must add one or more tokens to it. These tokens are then used in your API requests or anywhere else an API key is required for authentication. Each API key can have multiple tokens.

API keys and their tokens inherit the permissions of the account under which they are created. If the API key is created under your personal account, it will have the same permissions as your account. If it is created under a service account, it will inherit the permissions of that service account.

{% hint style="info" %}
To create service accounts and their API keys, you must have Account Admin privileges (or an equivalent role).
{% endhint %}

### Create personal API keys and tokens <a href="#create-personal-api-keys-and-tokens" id="create-personal-api-keys-and-tokens"></a>

Use these steps to create an API key and personal access token (PAT) for your personal Harness account.

1. Go to your user profile in Harness.
2. Under **My API Keys**, select **API Key**.
3. Enter a **Name** for the API key. **Description** and **Tags** are optional.
4. Select **Save** to create your API key.
5. Select **Token** under your new API key.
6. Enter a **Name** for the token. **Description** and **Tags** are optional.
7. To set an expiration date for the token, select Set Expiration Date and enter the date in mm/dd/yyyy format. For more information about [token expiration](#token-expiry), see the section below.
8. Select **Generate Token** and copy the token.

   <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>The token is only displayed once. Store the token somewhere secure that you can access when you make API requests.</p><p>Your API keys carry many privileges. Don't store them in publicly-accessible areas.</p><p>After <a href="/spaces/3F2TpHXhur2QtQnORSM9/pages/vIDwX1CXdZzHCf3MoCts#rotate-tokens">rotating tokens</a> make sure you always use the new token.</p></div>

### Create service account API keys and tokens <a href="#create-service-account-api-keys-and-tokens" id="create-service-account-api-keys-and-tokens"></a>

Use these steps to create an API key and service account token (SAT) for a service account. To do this, you must have the Account Admin role or another role that provides [permissions](/harness-ai/use-harness-platform/automation/api/api-permissions-reference.md) to View, Create/Edit, Manage, and Delete service accounts.

1. If you haven't done so already, [create a Service Account](/harness-ai/use-harness-platform/platform-access-control/add-and-manage-service-account.md). The API key and token inherit the permissions of the service account they are associated with; therefore, make sure the service account has the necessary permissions.
2. In Harness, select **Account Settings**, and then select **Access Control**.
3. Select **Service Accounts** in the header, and then select the service account for which you want to create an API key.
4. Under **API Keys**, select **API Key**.
5. Enter a **Name** for the API key. **Description** and **Tags** are optional.
6. Select **Save** to create the API key.
7. Select **Token** under the new API key.
8. Enter a **Name** for the token. **Description** and **Tags** are optional.
9. If you want to set an expiration date for the token, select **Set Expiration Date** and enter an expiration date in `mm/dd/yyyy` format.
10. Select **Generate Token** and copy the token.

{% hint style="warning" %}
The token is only displayed once. Store the token somewhere secure that you can access when you make API requests.

API keys carry many privileges. Don't store them in publicly-accessible areas.

After [rotating tokens](/harness-ai/use-harness-platform/automation/api/add-and-manage-api-keys.md#rotate-tokens) make sure you always use the new token.
{% endhint %}

### Edit API keys <a href="#edit-api-keys" id="edit-api-keys"></a>

Use these steps to edit the name, description, or tags for an API key. To edit tokens under API keys, go to [edit tokens](#edit-tokens) and [rotate tokens](#rotate-tokens).

{% tabs %}
{% tab title="Edit personal API keys" %}

1. Go to your user profile in Harness.
2. Under **My API Keys**, select **More Options** (⋮) next to the key you want to edit, and then select **Edit**.
3. You can edit the name, description, and tags. You can't edit the Id.
4. Select **Save**.
   {% endtab %}

{% tab title="Edit service account API keys" %}

1. In Harness, select **Account Settings**, and then select **Access Control**.
2. Select **Service Accounts** in the header, and then select the service account for which you want to edit an API key.
3. Select **More Options** (⋮) next to the key you want to edit, and then select **Edit**.
4. You can edit the name, description, and tags. You can't edit the ID.
5. Select **Save**.
   {% endtab %}
   {% endtabs %}

### Edit tokens <a href="#edit-tokens" id="edit-tokens"></a>

Use these steps to edit the name, description, tags, and expiration dates of tokens under API keys. You can also [rotate tokens](#rotate-tokens).

{% tabs %}
{% tab title="Edit personal access tokens" %}

1. Go to your user profile in Harness.
2. Under **My API Keys**, expand the token that you want to edit, select **More Options** (⋮), and then select **Edit**.
3. You can edit the name, description, tags, and expiration date. You can't edit the Id or the token's value.
4. Select **Save**.
   {% endtab %}

{% tab title="Edit service account tokens" %}

1. In Harness, select **Account Settings**, and then select **Access Control**.
2. Select **Service Accounts** in the header, and then select the service account for which you want to edit a token.
3. Select the API key that has the token you want to edit.
4. Select **More Options** (⋮) next to the token you want to edit, and then select **Edit**.
5. You can edit the name, description, tags, and expiration date. You can't edit the ID or the token's value.
6. Select **Save**.
   {% endtab %}
   {% endtabs %}

### Rotate tokens <a href="#rotate-tokens" id="rotate-tokens"></a>

As a security best practice, rotate tokens periodically. You can rotate tokens in Harness for symmetric encryption.

{% tabs %}
{% tab title="Rotate personal access tokens" %}

1. Go to your user profile in Harness.
2. Under **My API Keys**, expand the token that you want to rotate, select **More Options** (⋮), and then select **Rotate Token**.
3. If you want to set an expiration date for the token, select **Set Expiration Date** and enter an expiration date in `mm/dd/yyyy` format.
4. Select **Rotate Token** and copy the token.
   {% endtab %}

{% tab title="Rotate service account tokens" %}

1. In Harness, select **Account Settings**, and then select **Access Control**.
2. Select **Service Accounts** in the header, and then select the service account for which you want to rotate a token.
3. Select the API key that has the token you want to rotate.
4. Select **More Options** (⋮) next to the token you want to rotate, and then select **Rotate Token**.
5. If you want to set an expiration date for the token, select **Set Expiration Date** and enter an expiration date in `mm/dd/yyyy` format.
6. Select **Rotate Token** and copy the token.
   {% endtab %}
   {% endtabs %}

{% hint style="warning" %}
The token is only displayed once. Store the token somewhere secure that you can access when you make API requests.

API keys carry many privileges. Don't store them in publicly-accessible areas.

After rotating tokens make sure you always use the new token.
{% endhint %}

### Delete API keys <a href="#delete-api-keys" id="delete-api-keys"></a>

Use these steps to delete an API key and all of its tokens. To delete individual tokens under API keys, go to [delete tokens](#delete-tokens).

{% tabs %}
{% tab title="Edit personal API keys" %}

1. Go to your user profile in Harness.
2. Under **My API Keys**, select **More Options** (⋮) next to the key you want to delete, and then select **Delete**.
   {% endtab %}

{% tab title="Edit service account API keys" %}

1. In Harness, select **Account Settings**, and then select **Access Control**.
2. Select **Service Accounts** in the header, and then select the service account for which you want to delete an API key.
3. Select **More Options** (⋮) next to the key you want to delete, and then select **Delete**.
   {% endtab %}
   {% endtabs %}

### Delete tokens <a href="#delete-tokens" id="delete-tokens"></a>

{% tabs %}
{% tab title="Delete personal access tokens" %}

1. Go to your user profile in Harness.
2. Under **My API Keys**, expand the token that you want to delete, select **More Options** (⋮), and then select **Delete**.
   {% endtab %}

{% tab title="Delete service account tokens" %}

1. In Harness, select **Account Settings**, and then select **Access Control**.
2. Select **Service Accounts** in the header, and then select the service account for which you want to delete a token.
3. Select the API key that has the token you want to delete.
4. Select **More Options** (⋮) next to the token you want to delete, and then select **Delete**.
   {% endtab %}
   {% endtabs %}

### Token Expiry <a href="#token-expiry" id="token-expiry"></a>

When creating a token, you can choose how long it stays active. You can set it to expire in 30, 90, or 180 days — or pick a custom date. If you don't want it to expire, select No expiration.

To set the expiration, Go to Profile Overview → My API Keys → Token.

You can set expiration for both User tokens and Service Account tokens.

{% hint style="info" %}
Token expiration events are recorded in the audit logs. Expiration is checked every 5 minutes, so there may be a delay of up to 5 minutes between when a token expires and when the event is logged.
{% endhint %}

### Legacy Split (reference only) <a href="#legacy-split-reference-only" id="legacy-split-reference-only"></a>

<details>

<summary>View Legacy Split guidance</summary>

{% hint style="warning" %}
**MIGRATED FROM SPLIT?**

This documentation describes the **Split legacy** Admin API keys experience.

If your organization is using Harness FME, API key behavior and the UI may differ. For more information, see [RBAC for Split Admins](/feature-management-experimentation/troubleshooting-and-resources/split-to-harness-migration/administering-migrated-account.md#admin-api-keys).
{% endhint %}

FME [SDKs](/feature-management-experimentation/new-to-fme/sdks-and-customer-deployed-components.md) and [Admin API](https://docs.split.io/reference) both require API keys for authentication.

In Harness FME, there are three types of keys:

* **Server-side** type API keys are recommended to use with SDKs that live in your infrastructure (for example, your servers)
* **Client-side** type API keys are for SDKs living in public environments (for example, browsers or mobile clients)
* **Admin** type API Keys are used for access to Harness FME's [Admin API endpoints](https://docs.split.io/reference).

{% hint style="danger" %}
**KEEP YOUR SERVER-SIDE AND ADMIN KEYS PRIVATE**

Never expose Admin and server-side keys in untrusted contexts. Do not put your server-side or Admin API keys in client-side JavaScript or mobile SDKs. FME has special browser keys that you can use in client-side JavaScript, Android, and iOS. If you accidentally expose your API key, revoke it in the **APIs** tab in **Account settings**.

Be sure to copy your API Key once it's generated. For security purposes, you won’t see the key again.
{% endhint %}

**Managing your API keys**

To manage your API keys, go to the **API keys** tab in your **Admin Settings** page. On this page you can:

* See a list of all your existing API keys.
* Add additional API keys by clicking **Add API key** in the top right.
* Revoke existing API keys
* Clone existing API keys

**Adding server-side and client-side API keys**

To add one of these API keys, do the following:

1. From the left navigation, click the **profile button** at the bottom, and then select **Admin settings**.
2. Click **API keys**. The API key page appears.

   ![](/files/UqIHqwaNWT6nmkOy7n12)
3. From the Admin API keys tab, click **Actions** and then **Create SDK API key** . The Create SDK API key view appears.

   ![](/files/GnEVGY2oVuN231Yz0HpX)
4. Enter a name for this API Key to let other users know what it’s used for.
5. Select **Server-side** or **Client-side** as the type depending if you use this key to get treatments for a back end service or your user interface.
6. Select one environment that the key has access to fetch a feature flag and segment information from.
7. Click the **Create API key** button to create the key.

**Adding Admin API keys**

1. From the left navigation, click the **profile button** at the bottom and then select Admin settings.
2. Click **API keys**. The API key page appears.
3. From the Admin API keys tab, click **Actions** and then **Create Admin API**. The Create Admin API key view appears.

   ![](/files/vj3dm0QlDUBgv7Mx4qWv)
4. Enter a name for this API key to let other users what it's used for.
5. Select **All environments** or **Restrict to specific environments** to control the restrictions that this API Key has access to. If you select Restrict to specific environments, select one or more environments that the key has access to in one project.
6. Click the **Create API key** button. A new API key and access token are now created.

   ![](/files/R474jLKHxyMr2gvMwqns)

**Cloning API keys**

The Clone API keys action creates a new API key with access levels the same as the key being cloned. To clone an API key, do the following:

1. From the left navigation, click the **profile button** at the bottom and then select **Admin settings**.
2. Click **API keys**. The API key page appears.
3. From the Admin API keys tab, click **Clone** on the desired key. The Clone API key view appears.

   ![](/files/CDLyt5z70so0FVV2yHlc)
4. Enter a new name for the cloned key.
5. The Key scope section shows the original key’s scope that is applied to this new key.
6. Click the **Clone API key** button to create the cloned key.

**Endpoint restrictions for Admin API keys**

If you restrict an API Key to one or more environments, the following are the Admin API endpoints that are restricted:

* [Projects](https://docs.split.io/reference#get-workspaces) (formerly called Workspaces). All calls return a 401
* [Environments](https://docs.split.io/reference#environments-overview). All calls return a 401
* [Traffic Types](https://docs.split.io/reference#traffic-types-overview). All calls return a 401
* [Attributes](https://docs.split.io/reference#attributes-overview). All calls return a 401
* [Identities](https://docs.split.io/reference#identities-overview). All calls using an environment the key is not restricted for return a 401
* [Segments](https://docs.split.io/reference#segments-overview). All calls using an environment the key is not restricted for return a 401
* [Feature flags](https://docs.split.io/reference/feature-flag-overview). All calls using an environment the key is not restricted for return a 401
* [Change Requests](https://docs.split.io/reference#change-request-overview). All calls return a 401
* [Tags](https://docs.split.io/reference#tags-overview). All calls return a 401

**Managing Admin API key roles and scopes**

Harness FME enables you to restrict the access level of API keys in two ways:

1. Specifying **roles** for the API key: This limits what resource types an API key can access
2. Specifying a **scope** for the API key: This limits the reach of the API key across [environments](/feature-management-experimentation/management-and-administration/environments.md), a [project](/feature-management-experimentation/management-and-administration/projects.md), or the whole account.

While FME client-side and server-side SDK API keys are always scoped to a specific *environment*, Admin API keys can be tuned to granular access levels by creating them with a **role** and **scope** [using the Harness FME API](https://docs.split.io/reference/create-an-api-key). This page describes the roles and scopes that can be applied when creating ***Admin API keys***.

**Choose the right role**

The role given to an Admin API key aims to limit the access and operations a key can perform within FME within two functional areas: Administrative Permissions and Resource (Feature Flag & Segment) Permissions.

|                                         | Role                       | String Identifier          | Permission Granted                                                                                                                                                                                                                                    |
| --------------------------------------- | -------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Administrative Permissions              | Full Permissions Role      | API\_ALL\_GRANTED          | A key with this role grants access to all of your Account’s settings and resources via FME API.                                                                                                                                                       |
|                                         | Api Key Role               | API\_APIKEY                | A key with this role allows the creation and deletion of other API Keys.                                                                                                                                                                              |
|                                         | Account Administrator Role | API\_ADMIN                 | Reduced Admin capabilities. This role enables administration of the account from the API. However, this role excludes permission to manage API keys and the following resources: feature flags segments, change requests, tags, and rollout statuses. |
|                                         | Project Administrator Role | API\_WORKSPACE\_ADMIN      | Admin capabilities within a project (formerly called a workspace), similar to API\_ADMIN, but excluding permission to manage users and groups.                                                                                                        |
| **Resource Permissions:** Feature Flags | Feature Flag Viewer Role   | API\_FEATURE\_FLAG\_VIEWER | View-only access to feature flags, including permission to view associated change requests and rollout-board information.                                                                                                                             |
|                                         | Feature Flag Owner Role    | API\_FEATURE\_FLAG\_EDITOR | Grants access to all feature flag operations including operations related to associated tags, change requests and rollout-board information.                                                                                                          |
| **Resource Permissions:** Segments      | Segment Viewer Role        | API\_SEGMENT\_VIEWER       | View-only access to segments including associated tags and change requests.                                                                                                                                                                           |
|                                         | Segment Owner Role         | API\_SEGMENT\_EDITOR       | Grants access to all segment operations including operations related to associated tags and change requests.                                                                                                                                          |

Note that roles can be combined together at the time an API key is created to provide the appropriate set of permissions needed to accomplish specific tasks.

**Choose the right scope**

An API key can be scoped to limit its reach to:

* Specific environment(s): The API key will grant access to manage the resources (flags, segments, etc.) only within the specific set of environments that are enumerated at the time the API key is created.
* A specific project: The API key will grant access to manage the resources (flags, segments, traffic types, etc.) within only a single project. Access is also granted to manage future environments created within that project.
* The whole account: The API key will grant access to reach resources across the whole FME account. Granted access is effectively unscoped.

**Create a restricted API key**

You can use the FME API to create an Admin API key that has a restricted role or that leverages project and environment scopes. You can also restrict scope of an Admin API key to specific environments in the FME UI. Both approaches are described below.

**Using the FME API to manage roles and scopes**

Roles and scopes are assigned to an `Admin` API key (`"apiKeyType": "admin"`) at the moment of its creation via the FME API. Go to [Create an API key](https://docs.split.io/reference/create-an-api-key) to learn more.

Some important considerations:

* Roles and scopes are not editable. A role or scope cannot be changed for an API key after it is created.
* An Admin API Key cannot be used to create another with a broader scope than its own. When creating a new API key, the API key used to [authenticate the request](https://docs.split.io/v2-dev/reference/authentication) must have an equal or greater scope than the scope of the new API key.
* In order to create a new API key, the API key used to [authenticate the request](https://docs.split.io/v2-dev/reference/authentication) must have either the **API\_ALL\_GRANTED** and/or the **API\_APIKEY** role assigned.
* If no value is specified, by default the **API\_ALL\_GRANTED** role is assigned.
* If no scope is specified, by default the account-wide scope is assigned.

The POST API Key endpoint takes a JSON attribute, used to pass in the desired role. For an ***Admin key with full permissions***, here’s a sample payload you can send to create the role and its expected response.

```json
POST: /internal/api/v2/apiKeys
{
  "name": "my_first_restricted_apikey",
  "apiKeyType": "admin",
  "workspace": null,
  "environments": [],
  "roles": ["API_ALL_GRANTED"] 
}
```

```json
Response:
{
  "organization": {
    "type": "Organization",
    "id": "your-account-id"
  },
  "environments": [
    {
      "type": "Environment",
      "id": "<<GLOBAL>>"
    }
  ],
  "name": "my_first_restricted_apikey",
  "createdBy": {
    "type": "api_key",
    "id": "641mm**********************"
  },
  "createdAt": 1682722168424,
  "apiKeyType": "admin",
  "roles": [
    "API_ALL_GRANTED"
  ],
  "type": "api_key",
  "key": "b9lnhf***************************"
}
```

Be sure to copy your Admin API key (Line 34 in above example) once it's generated. For security purposes, you won't see the key again.

This is another example of a request to create an ***Admin API key that is scoped to a project***.

```json
POST: /internal/api/v2/apiKeys`
{
  "name": "my_project_admin_api_key",
  "apiKeyType": "admin",
  "workspace": {
     "type": "workspace",
     "id": "your-project-id"
  },
  "environments": [],
  "roles": ["API_WORKSPACE_ADMIN"]
}
```

```json
Response:
{
  "organization": {
    "type": "Organization",
    "id": "your-account-id",
  },
  "environments": [
     {
       "type": "environment",
       "id": "<<GLOBAL>>"
     }
  ],
  "name": "my_project_admin_api_key",
  "createdBy": {
    "type": "api_key",
    "id": "641mm**********************"
  },
  "createdAt": 1691762215442,
  "apiKeyType": "admin",
  "workspace": {
    "type": "workspace",
    "id": "Your-Project-id"
  },
  "roles": [
    "API_WORKSPACE_ADMIN"
  ],
  "type": "api_key",
  "key": "b9lnhf***************************"
}
```

**Using the FME UI to manage scopes**

You can also use the Admin settings section in the Harness FME to create an Admin API key that is scoped to specific environment(s). At this time, you cannot use this UI to specify a specific role or project scope. Note that all SDK API keys are inherently scoped to a single environment.

![](/files/vj3dm0QlDUBgv7Mx4qWv)

**Manage a restricted API key**

You can revoke and clone restricted Admin API keys using the FME UI as you would an unrestricted key.

![](/files/l4q7YGOG7m7i1TmAOxKD)

**Ensure your key has the appropriate role to use the API endpoints**

Each FME API endpoint has a list of accepted roles that the endpoint will look for on the bearer key that you used to [authorize your API request](https://docs.split.io/v2-dev/reference/authentication). You can see the list of accepted roles by navigating to a specific resource in our [API documentation](https://docs.split.io/v2/reference/create-an-api-key).

Additionally, [error codes](https://docs.split.io/v2/reference/error-codes) have been created for cases where requests do not have the appropriate role in the bearer token that was used.

</details>