# Add an integration key

`POST /v1/integrations`

Add a Hugging Face token. The organization's first one becomes the
default. The answer never holds the token.

Needs `integrations:write` and Contributor or above on the organization.

- Base URL: `https://junction-api.qualiastudios.dev`
- Authentication: an API key in the `X-API-Key` header, or `Authorization: Bearer …`

## Request body

Required: `application/json` `object`

```yaml
properties:
  provider:
    type: string
    const: huggingface
    description: huggingface (a token new runs use)
  name:
    type: string
    maxLength: 15
    minLength: 1
    description: The token's name
  secret:
    type: string
    format: password
    description: The token itself; it starts with "hf_"
    writeOnly: true
additionalProperties: false
type: object
required:
  - provider
  - name
  - secret
title: IntegrationCreateRequest
description: |-
  Add an integration key. The secret is sent here once and never read
  back.
```

## Responses

- `201` Successful Response: `application/json` `Integration`
- `401` Invalid or missing API key: `application/json` `ErrorResponse`
- `403` Missing integrations:write, or a Viewer's key: `application/json` `ErrorResponse`
- `404` Not found or access denied: `application/json` `ErrorResponse`
- `422` The body names a bad field: `application/json` `ErrorResponse`

## Schemas

```yaml
Integration:
  properties:
    id:
      type: string
      format: uuid
      description: The integration key's ID
    provider:
      type: string
      const: huggingface
      description: The service the key is for
    name:
      type: string
      description: The key's name
    last4:
      description: The key's last four characters; null for a key shorter than 12
      type:
        - string
        - "null"
    is_default:
      type: boolean
      description: The Hugging Face token new runs use
    created_by:
      type: string
      format: uuid
      description: The person who added it
    created_at:
      type: string
      format: date-time
      description: When it was added
    expires_at:
      type: string
      format: date-time
      description: When it expires
  type: object
  required:
    - id
    - provider
    - name
    - is_default
    - created_by
    - created_at
    - expires_at
  title: Integration
  description: One integration key, without its value.
ErrorResponse:
  properties:
    detail:
      type: string
      description: Error message describing what went wrong
  type: object
  required:
    - detail
  title: ErrorResponse
  description: Standard error response.
```