Create a Microsoft Graph credential

Create a Microsoft Graph app-only credential for connecting Microsoft mailboxes. Before saving the credential, Woodpecker verifies that the provided tenant ID, client ID, and client secret can be used to retrieve a Microsoft Graph access token.

The client_secret is encrypted before it is stored and is not returned in the response.

Request

Endpoint

POST https://api.woodpecker.co/rest/v2/mailboxes/microsoft/credentials

Headers

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

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

Body

{
  "tenant_id": "bbfb2db7-aaf4-4f7c-9dc2-2c9160d1cb32",
  "client_id": "e1c6ac69-480e-4a17-9b85-3467967bd179",
  "client_secret": "your-client-secret",
  "secret_expires_at": "2027-11-28T23:59:59Z",
  "name": "MS Graph app"
}

Body schema

Field	Type	Required	Description
tenant_id	string	Yes	Microsoft Entra tenant ID
client_id	string	Yes	Microsoft Entra application client ID
client_secret	string	Yes	Client secret for the Microsoft app registration
secret_expires_at	string	Yes	Client secret expiration date in ISO 8601 format
name	string	No	Credential name. If omitted, Woodpecker assigns a default name

Request samples

Create a credential

cURL

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/mailboxes/microsoft/credentials" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "tenant_id": "bbfb2db7-aaf4-4f7c-9dc2-2c9160d1cb32",
    "client_id": "e1c6ac69-480e-4a17-9b85-3467967bd179",
    "client_secret": "your-client-secret",
    "secret_expires_at": "2027-11-28T23:59:59Z",
    "name": "MS Graph app"
  }'

Python

import requests

def create_microsoft_graph_credential():
  url = "https://api.woodpecker.co/rest/v2/mailboxes/microsoft/credentials"
  headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json",
  }
  payload = {
    "tenant_id": "bbfb2db7-aaf4-4f7c-9dc2-2c9160d1cb32",
    "client_id": "e1c6ac69-480e-4a17-9b85-3467967bd179",
    "client_secret": "your-client-secret",
    "secret_expires_at": "2027-11-28T23:59:59Z",
    "name": "MS Graph app",
  }

  response = requests.post(url, headers=headers, json=payload)

  if response.status_code == 201:
    print(response.json())
  else:
    print("Request failed:", response.status_code, response.text)

if __name__ == "__main__":
  create_microsoft_graph_credential()

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

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

  public static void main(String[] args) {
    createMicrosoftGraphCredential();
  }

  public static void createMicrosoftGraphCredential() {
    try {
      String url = "https://api.woodpecker.co/rest/v2/mailboxes/microsoft/credentials";
      String jsonData = """
        {
          "tenant_id": "bbfb2db7-aaf4-4f7c-9dc2-2c9160d1cb32",
          "client_id": "e1c6ac69-480e-4a17-9b85-3467967bd179",
          "client_secret": "your-client-secret",
          "secret_expires_at": "2027-11-28T23:59:59Z",
          "name": "MS Graph app"
        }
        """;

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("x-api-key", API_KEY)
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(jsonData))
        .build();

      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

      if (response.statusCode() == 201) {
        System.out.println(response.body());
      } else {
        System.err.println("Request failed: " + response.statusCode());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require("axios");

async function createMicrosoftGraphCredential() {
  const url = "https://api.woodpecker.co/rest/v2/mailboxes/microsoft/credentials";
  const headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  };
  const data = {
    tenant_id: "bbfb2db7-aaf4-4f7c-9dc2-2c9160d1cb32",
    client_id: "e1c6ac69-480e-4a17-9b85-3467967bd179",
    client_secret: "your-client-secret",
    secret_expires_at: "2027-11-28T23:59:59Z",
    name: "MS Graph app"
  };

  try {
    const response = await axios.post(url, data, { headers });

    if (response.status === 201) {
      console.log(response.data);
    } else {
      console.error("Request failed:", response.status);
    }
  } catch (error) {
    console.error("Request error:", error.response?.status || error.message);
  }
}

createMicrosoftGraphCredential();

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
  'base_uri' => 'https://api.woodpecker.co/rest/v2/',
  'headers'  => [
    'x-api-key'     => getenv('WOODPECKER_API_KEY'),
    'Content-Type'  => 'application/json',
  ],
]);

try {
  $response = $client->post('mailboxes/microsoft/credentials', [
    'json' => [
      'tenant_id'          => 'bbfb2db7-aaf4-4f7c-9dc2-2c9160d1cb32',
      'client_id'          => 'e1c6ac69-480e-4a17-9b85-3467967bd179',
      'client_secret'      => 'your-client-secret',
      'secret_expires_at'  => '2027-11-28T23:59:59Z',
      'name'               => 'MS Graph app',
    ],
  ]);
  echo $response->getStatusCode(), "\n";
  echo $response->getBody(), "\n";
} catch (RequestException $e) {
  echo "Error: ", $e->getMessage(), "\n";
  if ($e->hasResponse()) {
    echo $e->getResponse()->getBody(), "\n";
  }
}

Response

Response examples

201

The credential was created.

{
  "credential_id": 22334455,
  "tenant_id": "bbfb2db7-aaf4-4f7c-9dc2-2c9160d1cb32",
  "client_id": "e1c6ac69-480e-4a17-9b85-3467967bd179",
  "secret_expires_at": "2027-11-28T23:59:59Z",
  "name": "MS Graph app"
}

Body schema

Field	Type	Description
credential_id	integer	Created credential ID
tenant_id	string	Microsoft Entra tenant ID
client_id	string	Microsoft Entra application client ID
secret_expires_at	string	Client secret expiration date in ISO 8601 format
name	string	Credential name.

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

Please review the request URL.

{
  "title": "Not Found",
  "status": 404,
  "detail": "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

422

Invalid request or malformed request syntax. The request can also fail when the body is valid JSON, but the credential cannot be saved.

{
  "message": "INVALID_CLIENT_SECRET"
}

Body schema

Field	Type	Description
message	string	Validation error message. Possible values: Missing tenantId - tenant_id is missing Missing clientId - client_id is missing Missing client secret - client_secret is missing MISSING_SECRET_EXPIRES_AT - secret_expires_at is missing SECRET_EXPIRES_AT_NOT_IN_FUTURE - secret_expires_at is not in the future INVALID_CLIENT_SECRET - Microsoft Graph rejected the provided credential

500

Unexpected 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