> ## Documentation Index
> Fetch the complete documentation index at: https://docs.semust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate with the Semust API

## Overview

The Semust API uses custom header authentication. All requests must include two authentication headers with your API credentials.

## Required Headers

| Header                | Type   | Description            |
| --------------------- | ------ | ---------------------- |
| `SEMUST-API-USER`     | string | Your API user username |
| `SEMUST-API-PASSWORD` | string | Your API user password |

<Warning>
  Both headers are required. Missing either header will result in a `401` error.
</Warning>

## Creating API Users

To create API credentials:

<Steps>
  <Step title="Access the Dashboard">
    Go to the [API Access](https://app.semust.com/api/access) page in your dashboard.
  </Step>

  <Step title="Create API User">
    Click **"Create API User"** to generate new credentials.
  </Step>

  <Step title="Copy Credentials">
    Copy the username and password. Use them in the `SEMUST-API-USER` and `SEMUST-API-PASSWORD` headers in your requests.
  </Step>
</Steps>

You can create multiple API users per account for different applications or environments.

<Warning>
  **Security:** Never expose your API credentials in client-side code or public repositories. Store them securely in environment variables.
</Warning>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://data.semust.com/v1/serp \
    -H "Content-Type: application/json" \
    -H "SEMUST-API-USER: your_username" \
    -H "SEMUST-API-PASSWORD: your_password" \
    -d '{"keyword": "best seo tools"}'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://data.semust.com/v1/serp",
      headers={
          "SEMUST-API-USER": "your_username",
          "SEMUST-API-PASSWORD": "your_password",
      },
      json={"keyword": "best seo tools"},
  )

  if response.status_code == 200:
      data = response.json()
      print(data)
  else:
      print(f"Error [{response.status_code}]: {response.text}")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://data.semust.com/v1/serp", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "SEMUST-API-USER": "your_username",
      "SEMUST-API-PASSWORD": "your_password",
    },
    body: JSON.stringify({ keyword: "best seo tools" }),
  });

  if (response.ok) {
    const data = await response.json();
    console.log(data);
  } else {
    console.error(`Error [${response.status}]: ${await response.text()}`);
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "io"
      "net/http"
  )

  func main() {
      payload := map[string]string{"keyword": "best seo tools"}
      body, _ := json.Marshal(payload)

      req, _ := http.NewRequest("POST",
          "https://data.semust.com/v1/serp",
          bytes.NewBuffer(body))
      req.Header.Set("Content-Type", "application/json")
      req.Header.Set("SEMUST-API-USER", "your_username")
      req.Header.Set("SEMUST-API-PASSWORD", "your_password")

      resp, err := (&http.Client{}).Do(req)
      if err != nil {
          fmt.Printf("Request failed: %v\n", err)
          return
      }
      defer resp.Body.Close()

      respBody, _ := io.ReadAll(resp.Body)
      fmt.Println(string(respBody))
  }
  ```

  ```php PHP theme={null}
  <?php

  $payload = json_encode(["keyword" => "best seo tools"]);

  $ch = curl_init("https://data.semust.com/v1/serp");
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Content-Type: application/json",
      "SEMUST-API-USER: your_username",
      "SEMUST-API-PASSWORD: your_password",
  ]);

  $response = curl_exec($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($httpCode === 200) {
      $data = json_decode($response, true);
      print_r($data);
  } else {
      echo "Error [{$httpCode}]: {$response}\n";
  }
  ```
</CodeGroup>

## Authentication Errors

If authentication fails, you will receive a `401` status code with the following error:

```json Error Response theme={null}
{
  "error": "Authentication failed — invalid username or password",
  "code": "INVALID_API_KEY"
}
```

| Status | Code              | Description                          |
| ------ | ----------------- | ------------------------------------ |
| 401    | `INVALID_API_KEY` | The provided credentials are invalid |

<Tip>
  Double-check that both `SEMUST-API-USER` and `SEMUST-API-PASSWORD` headers are present and contain the correct values from your [API Access](https://app.semust.com/api/access) page.
</Tip>