Create an API key for a company

This endpoint allows you to generate a new API key for the specified company, which can be used to authenticate API requests. The response contains the newly created API key.

Request

Endpoint

POST https://api.woodpecker.co/rest/v2/agency/companies/{company_id}/api_keys

Headers

x-api-key: {YOUR_API_KEY}
Content-Type: application/json

For details on how to authenticate your requests, please see the authentication guide.

Parameters

Parameter	Required	Type	Description
company_id	Yes	integer	Path parameter - the ID of the company for which the API key will be generated

Body

{
  "label": "string"
}

Body schema

Field	Required	Type	Description
label	Yes	string	A descriptive name assigned to the key

Request sample

Create API keys

cURL

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/agency/companies/{company_id}/api_keys" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "label": "string"
  }'

Python

import requests

def create_api_key(company_id, label):
  url = f"https://api.woodpecker.co/rest/v2/agency/companies/{company_id}/api_keys"
  headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  }
  data = {
    "label": label
  }
  
  response = requests.post(url, headers=headers, json=data)
  if response.status_code == 201:
    return response.json()
  else:
    raise Exception(f"POST request failed: {response.status_code}, {response.text}")

if __name__ == "__main__":
  try:
    company_id = 123  # Example company ID
    label = "string"
    data = create_api_key(company_id, label)
    print("POST response:", data)
  except Exception as e:
    print("Error:", e)

Java

public class WoodpeckerApiClient {
  private static final String API_KEY = "{YOUR_API_KEY}";

  public static void main(String[] args) {
    int companyId = 123; // Example company ID
    String label = "string";
    createApiKey(companyId, label);
  }

  public static void createApiKey(int companyId, String label) {
    try {
      String url = "https://api.woodpecker.co/rest/v2/agency/companies/" + companyId + "/api_keys";
      String jsonData = "{ \"label\": \"" + label + "\" }";
      java.net.http.HttpClient client = java.net.http.HttpClient.newHttpClient();
      java.net.http.HttpRequest request = java.net.http.HttpRequest.newBuilder()
        .uri(new java.net.URI(url))
        .header("x-api-key", API_KEY)
        .header("Content-Type", "application/json")
        .POST(java.net.http.HttpRequest.BodyPublishers.ofString(jsonData))
        .build();

      java.net.http.HttpResponse<String> response = client.send(request, java.net.http.HttpResponse.BodyHandlers.ofString());
      if (response.statusCode() == 201) {
        System.out.println("POST response: " + response.body());
      } else {
        System.err.println("POST request failed: " + response.statusCode());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require('axios');

async function createApiKey(companyId, label) {
  const url = `https://api.woodpecker.co/rest/v2/agency/companies/${companyId}/api_keys`;
  const headers = {
    'x-api-key': '{YOUR_API_KEY}',
    'Content-Type': 'application/json'
  };
  const data = { label: label };

  try {
    const response = await axios.post(url, data, { headers });
    if (response.status === 201) {
      console.log('POST response:', response.data);
    } else {
      console.error('POST request failed:', response.status);
    }
  } catch (error) {
    console.error('POST request failed:', error.response ? error.response.status : error.message);
  }
}

(async () => {
  const companyId = 123; // Example company ID
  const label = "string";
  await createApiKey(companyId, label);
})();

Response

Response examples

201

Created API key

{
  "api_key": "string"
}

Body schema

Field	Type	Description
api_key	string	newly generated API key

400

Missing request body:

Status: 400
Body: None

Malformed request syntax:

{
  "title": "Bad request",
  "status": 400,
  "detail": "Your request was not valid. Please check the body for any mistakes",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

401

An issue with authorization. Please review the authorization guide

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid api key",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

404

The requested company does not exists, is inactive, or the request URL is incorrect

{
  "title": "Not Found",
  "status": 404,
  "detail": "No active company found" | "Requested resource does not exist",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

500

Unknown error, please try again later

{
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error has occurred. Please try again later.",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC