> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Shashank-H/gaiter-gaurd/llms.txt
> Use this file to discover all available pages before exploring further.

# Services

> Manage third-party API service configurations and encrypted credentials

<Info>All service endpoints require authentication via Bearer token.</Info>

## List services

<api>GET /services</api>

Retrieve all API services configured for the authenticated user.

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer <jwt>`
</ParamField>

### Response

Returns an array of service objects.

<ResponseField name="services" type="object[]">
  <Expandable title="properties">
    <ResponseField name="id" type="number">
      Unique service identifier.
    </ResponseField>

    <ResponseField name="userId" type="number">
      Owner user ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      Service name.
    </ResponseField>

    <ResponseField name="baseUrl" type="string">
      Base URL for the service API.
    </ResponseField>

    <ResponseField name="authType" type="string">
      Authentication type: `api_key`, `bearer`, `basic`, or `oauth2`.
    </ResponseField>

    <ResponseField name="credentials" type="object">
      Object containing credential keys (values are masked for security).
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of service creation.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp of last update.
    </ResponseField>
  </Expandable>
</ResponseField>

### Status codes

* `200` - Services retrieved successfully
* `401` - Unauthorized (missing or invalid token)
* `500` - Internal server error

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.gaiterguard.com/services \
    --header 'Authorization: Bearer <jwt>'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gaiterguard.com/services', {
    headers: {
      'Authorization': 'Bearer <jwt>'
    }
  });
  const data = await response.json();
  ```

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

  response = requests.get(
      'https://api.gaiterguard.com/services',
      headers={'Authorization': 'Bearer <jwt>'}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "id": 1,
      "userId": 1,
      "name": "GitHub API",
      "baseUrl": "https://api.github.com",
      "authType": "bearer",
      "credentials": {
        "token": "***"
      },
      "createdAt": "2026-03-03T22:49:00.000Z",
      "updatedAt": "2026-03-03T22:49:00.000Z"
    }
  ]
  ```
</ResponseExample>

***

## Create service

<api>POST /services</api>

Create a new service with encrypted credentials.

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer <jwt>`
</ParamField>

### Request body

<ParamField body="name" type="string" required>
  Service name (1-255 characters).
</ParamField>

<ParamField body="baseUrl" type="string" required>
  Base URL for the service API. Must be a valid URL (max 512 characters).
</ParamField>

<ParamField body="authType" type="string" required>
  Authentication type. Must be one of: `api_key`, `bearer`, `basic`, `oauth2`.
</ParamField>

<ParamField body="credentials" type="object" required>
  Key-value pairs of credential names and values. At least one credential is required. Values are encrypted before storage.
</ParamField>

### Response

<ResponseField name="id" type="number">
  Unique service identifier.
</ResponseField>

<ResponseField name="userId" type="number">
  Owner user ID.
</ResponseField>

<ResponseField name="name" type="string">
  Service name.
</ResponseField>

<ResponseField name="baseUrl" type="string">
  Base URL for the service API.
</ResponseField>

<ResponseField name="authType" type="string">
  Authentication type.
</ResponseField>

<ResponseField name="credentials" type="object">
  Object containing credential keys (values are masked).
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of service creation.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of last update.
</ResponseField>

### Status codes

* `201` - Service created successfully
* `400` - Validation error (invalid request body)
* `401` - Unauthorized (missing or invalid token)
* `500` - Internal server error

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.gaiterguard.com/services \
    --header 'Authorization: Bearer <jwt>' \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "GitHub API",
      "baseUrl": "https://api.github.com",
      "authType": "bearer",
      "credentials": {
        "token": "ghp_xxxxxxxxxxxxx"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gaiterguard.com/services', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <jwt>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'GitHub API',
      baseUrl: 'https://api.github.com',
      authType: 'bearer',
      credentials: {
        token: 'ghp_xxxxxxxxxxxxx'
      }
    })
  });
  const data = await response.json();
  ```

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

  response = requests.post(
      'https://api.gaiterguard.com/services',
      headers={'Authorization': 'Bearer <jwt>'},
      json={
          'name': 'GitHub API',
          'baseUrl': 'https://api.github.com',
          'authType': 'bearer',
          'credentials': {
              'token': 'ghp_xxxxxxxxxxxxx'
          }
      }
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": 1,
    "userId": 1,
    "name": "GitHub API",
    "baseUrl": "https://api.github.com",
    "authType": "bearer",
    "credentials": {
      "token": "***"
    },
    "createdAt": "2026-03-03T22:49:00.000Z",
    "updatedAt": "2026-03-03T22:49:00.000Z"
  }
  ```

  ```json 400 theme={null}
  {
    "error": "At least one credential is required"
  }
  ```
</ResponseExample>

***

## Get service

<api>GET /services/:id</api>

Retrieve a single service by ID. Ownership is verified.

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer <jwt>`
</ParamField>

### Path parameters

<ParamField path="id" type="number" required>
  Service ID.
</ParamField>

### Response

<ResponseField name="id" type="number">
  Unique service identifier.
</ResponseField>

<ResponseField name="userId" type="number">
  Owner user ID.
</ResponseField>

<ResponseField name="name" type="string">
  Service name.
</ResponseField>

<ResponseField name="baseUrl" type="string">
  Base URL for the service API.
</ResponseField>

<ResponseField name="authType" type="string">
  Authentication type.
</ResponseField>

<ResponseField name="credentials" type="object">
  Object containing credential keys (values are masked).
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of service creation.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of last update.
</ResponseField>

### Status codes

* `200` - Service retrieved successfully
* `400` - Invalid service ID
* `401` - Unauthorized (missing or invalid token)
* `404` - Service not found
* `500` - Internal server error

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.gaiterguard.com/services/1 \
    --header 'Authorization: Bearer <jwt>'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gaiterguard.com/services/1', {
    headers: {
      'Authorization': 'Bearer <jwt>'
    }
  });
  const data = await response.json();
  ```

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

  response = requests.get(
      'https://api.gaiterguard.com/services/1',
      headers={'Authorization': 'Bearer <jwt>'}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": 1,
    "userId": 1,
    "name": "GitHub API",
    "baseUrl": "https://api.github.com",
    "authType": "bearer",
    "credentials": {
      "token": "***"
    },
    "createdAt": "2026-03-03T22:49:00.000Z",
    "updatedAt": "2026-03-03T22:49:00.000Z"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Service not found"
  }
  ```
</ResponseExample>

***

## Update service

<api>PUT /services/:id</api>

Update service details (name, baseUrl, or authType). To update credentials, use the credentials endpoint.

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer <jwt>`
</ParamField>

### Path parameters

<ParamField path="id" type="number" required>
  Service ID.
</ParamField>

### Request body

<ParamField body="name" type="string">
  Service name (1-255 characters). Optional.
</ParamField>

<ParamField body="baseUrl" type="string">
  Base URL for the service API. Must be a valid URL (max 512 characters). Optional.
</ParamField>

<ParamField body="authType" type="string">
  Authentication type. Must be one of: `api_key`, `bearer`, `basic`, `oauth2`. Optional.
</ParamField>

<Info>At least one field must be provided for update.</Info>

### Response

Returns the updated service object.

### Status codes

* `200` - Service updated successfully
* `400` - Validation error (invalid service ID or request body)
* `401` - Unauthorized (missing or invalid token)
* `404` - Service not found
* `500` - Internal server error

<RequestExample>
  ```bash cURL theme={null}
  curl --request PUT \
    --url https://api.gaiterguard.com/services/1 \
    --header 'Authorization: Bearer <jwt>' \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "GitHub Enterprise API"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gaiterguard.com/services/1', {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer <jwt>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'GitHub Enterprise API'
    })
  });
  const data = await response.json();
  ```

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

  response = requests.put(
      'https://api.gaiterguard.com/services/1',
      headers={'Authorization': 'Bearer <jwt>'},
      json={'name': 'GitHub Enterprise API'}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": 1,
    "userId": 1,
    "name": "GitHub Enterprise API",
    "baseUrl": "https://api.github.com",
    "authType": "bearer",
    "credentials": {
      "token": "***"
    },
    "createdAt": "2026-03-03T22:49:00.000Z",
    "updatedAt": "2026-03-03T23:15:00.000Z"
  }
  ```
</ResponseExample>

***

## Delete service

<api>DELETE /services/:id</api>

Delete a service. This cascades to delete all associated credentials and documentation.

<Warning>This action is irreversible. All agents using this service will no longer have access to it.</Warning>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer <jwt>`
</ParamField>

### Path parameters

<ParamField path="id" type="number" required>
  Service ID.
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message confirming deletion.
</ResponseField>

### Status codes

* `200` - Service deleted successfully
* `400` - Invalid service ID
* `401` - Unauthorized (missing or invalid token)
* `404` - Service not found
* `500` - Internal server error

<RequestExample>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://api.gaiterguard.com/services/1 \
    --header 'Authorization: Bearer <jwt>'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gaiterguard.com/services/1', {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer <jwt>'
    }
  });
  const data = await response.json();
  ```

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

  response = requests.delete(
      'https://api.gaiterguard.com/services/1',
      headers={'Authorization': 'Bearer <jwt>'}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "message": "Service deleted"
  }
  ```
</ResponseExample>

***

## Update credentials

<api>POST /services/:id/credentials</api>

Replace all credentials for a service. Existing credentials are deleted and replaced with the new ones.

<Warning>This replaces ALL credentials. Any credentials not included in the request will be removed.</Warning>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer <jwt>`
</ParamField>

### Path parameters

<ParamField path="id" type="number" required>
  Service ID.
</ParamField>

### Request body

<ParamField body="credentials" type="object" required>
  Key-value pairs of credential names and values. At least one credential is required. All values are encrypted before storage.
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message confirming credential update.
</ResponseField>

<ResponseField name="credentialKeys" type="string[]">
  Array of credential key names that were stored.
</ResponseField>

### Status codes

* `200` - Credentials updated successfully
* `400` - Validation error (invalid service ID or request body)
* `401` - Unauthorized (missing or invalid token)
* `404` - Service not found
* `500` - Internal server error

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.gaiterguard.com/services/1/credentials \
    --header 'Authorization: Bearer <jwt>' \
    --header 'Content-Type: application/json' \
    --data '{
      "credentials": {
        "token": "ghp_newtoken123456",
        "secret": "newsecret789"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gaiterguard.com/services/1/credentials', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <jwt>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      credentials: {
        token: 'ghp_newtoken123456',
        secret: 'newsecret789'
      }
    })
  });
  const data = await response.json();
  ```

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

  response = requests.post(
      'https://api.gaiterguard.com/services/1/credentials',
      headers={'Authorization': 'Bearer <jwt>'},
      json={
          'credentials': {
              'token': 'ghp_newtoken123456',
              'secret': 'newsecret789'
          }
      }
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "message": "Credentials updated",
    "credentialKeys": ["token", "secret"]
  }
  ```

  ```json 400 theme={null}
  {
    "error": "At least one credential is required"
  }
  ```
</ResponseExample>