API Quickstart

Updated 3 days ago by Rashmi Nanda Sahoo

This quickstart shows how to onboard Harness resources using the Harness APIs.

Objectives

You'll learn how to:

  • Authenticate to a Harness API.
  • Configure API Keys.
  • Onboard Harness resources using the Harness API.

Before You Begin

Step 1: Authenticate with Harness

The Harness API uses API Keys to authenticate requests. You can view and manage your API Keys in your User Profile.

Create API Key

  1. In Harness, navigate to your Profile.
  2. Click API Key. The API Key settings appear.
  3. Enter Name, Description, and Tags for your API.
  4. Click Save. The new API Key is created.

Create Personal Access Token

  1. To generate a Token for this API Key, click Token below the API Key you just created.
  2. In the New Token settings, enter a Name, Description, and Tags.
  3. To set an expiration date for this token, select Set Expiration Date.
  4. Enter date in Expiration Date (mm/dd/yyyy).
  5. Click Generate Token.
  6. Your new Token is generated.

Create Service Account Token

To generate a Service Access Token, you need to first create a Service Account and create an API Key under it.

  1. In Harness, click Home.
  2. In Account Setup, click Access Control.
  3. Click Service Accounts and then click the service account to which you want to add a new API Key. For step-by-step instructions to add a new Service Account, see Add and Manage Service Accounts.
  4. In the Service Account's settings page, click API Key.
  5. In the New API Key settings, enter Name, Description, and Tags.
  6. Click Save. The new API Key is created.

Generate Service Account Token

  1. To generate a Token for this API Key, click Token below the API Key you just created.
  2. In the New Token settings, enter Name, Description, and Tags.
  3. To set an expiration date for this token, select Set Expiration Date.
  4. Enter date in Expiration Date (mm/dd/yyyy).
  5. Click Generate Token.
  6. Your new Token is generated.
Your API keys carry many privileges, so be sure not to share them in publicly accessible areas. Make sure you always use the updated API Key value after you rotate the token. For more details, see Rotate Token.

Step 2: Create a Project via API

A Harness Project is a group of Harness modules and their Pipelines.

URL: https://app.harness.io/gateway/ng/api/projects?routingId={routingid}&accountIdentifier={accountid}&orgIdentifier={orgid}

HTTP Method: POST

Query ParamaccountId and routingId are your account identifier (ID), orgIdentifier is your org identifier(ID).

Request body: details of the project you want to create like name, description, identifier, tags, modules.

Swagger JSON: https://app.harness.io/prod1/ng/api/swagger.json

Swagger JSON for Pipeline: https://app.harness.io/prod1/pipeline/api/swagger.json

For more details on Harness APIs, see Harness API Reference.

Sample cURL
curl --location --request POST 'https://app.harness.io/gateway/ng/api/projects?accountIdentifier={accountidentifier}&routingId={accountidentifier}&orgIdentifier=DocExample' \
--header 'x-api-key: {api-key}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"project": {
"name": "SampleProject",
"orgIdentifier": "DocExample",
"color": "#0063F7",
"description": "",
"identifier": "SampleProject",
"tags": {},
"modules": []}
}'
Response
{"status":"SUCCESS","data":{"project":{"orgIdentifier":"DocExample","identifier":"SampleProject","name":"SampleProject","color":"#0063F7","modules":["CD","CI","CV","CF","CE","CORE","PMS","TEMPLATESERVICE"],"description":"","tags":{}},"createdAt":1630342745106,"lastModifiedAt":1630342745106},"metaData":null,"correlationId":"2291f56d-d284-42b7-9dab-c6640e4dbea7"}

Errors

Harness uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTPS Status Code

Summary

200 - OK

The request has been processed successfully on the server.

400 - Bad Request

The request was not processed successfully due to incorrect syntax or missing parameters.

401 - Unauthorized

The request was unauthorized due to an invalid API Key.

402 - Request Failed

The request cannot be processed.

403 - Forbidden

The API Key does not have permission to perform the request.

404 - Not Found

The requested resource does not exist.

500, 502, 503, 504 - Server Errors

The Harness server encountered an unexpected error.


Please Provide Feedback