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

# Generate Credential (Draft)

### Description

This endpoint allows you to **create a credential in draft state** without immediately publishing it. The credential can be reviewed and published later using the [Publish Credential](/api-guide/publish-credential) endpoint.

### Headers

<ParamField header="Authorization" type="string" required="true">
  Bearer YOUR\_API\_TOKEN — obtainable from **Hyperstack Dashboard → Settings → API Access**
</ParamField>

### Body Parameters

<ParamField body="recipient" type="object" required="true">
  Information about the recipient of the credential.
</ParamField>

<ParamField body="recipient.name" type="string" required="true">
  Full name of the recipient.
</ParamField>

<ParamField body="recipient.email" type="string" required="true">
  Email address of the recipient.
</ParamField>

<ParamField body="group_key" type="string" required="true">
  The unique key of the credential group in which this credential will be generated.
</ParamField>

<ParamField body="custom_attributes" type="object" required="false">
  Key-value pairs of custom attributes to embed in the credential. Keys must match the custom fields (prefixed with `custom_`) configured for your account.
</ParamField>

### Success Response Fields

<ResponseField name="success" type="boolean">
  Indicates whether the credential was successfully generated.
</ResponseField>

<ResponseField name="document_id" type="string">
  The unique ID of the newly created draft credential.
</ResponseField>

<ResponseField name="document_url" type="string">
  URL where the credential will be accessible once published.
</ResponseField>

<ResponseField name="status" type="string">
  Publication status of the credential. Will be `"draft"` for this endpoint.
</ResponseField>

<ResponseField name="recipient" type="object">
  Object containing `name` and `email` of the recipient.
</ResponseField>

<ResponseField name="group" type="object">
  Object containing `title`, `key`, and `code` of the credential group.
</ResponseField>

<ResponseField name="issued_on" type="string">
  ISO 8601 timestamp of when the credential record was created.
</ResponseField>

<ResponseField name="valid_until" type="string">
  ISO 8601 expiry timestamp. `null` if the credential does not expire.
</ResponseField>

<ResponseField name="metadata" type="object">
  Custom attribute values stored with the credential.
</ResponseField>

<ResponseField name="privacy" type="string">
  Visibility of the credential — `"public"` or `"private"`.
</ResponseField>

### Responses

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "status": "draft",
    "document_id": "j4nDvaxF6ehodPXI84p4X1yhQe7lrYgx",
    "document_url": "https://hyperstack.id/credential/j4nDvaxF6ehodPXI84p4X1yhQe7lrYgx",
    "recipient": { "name": "John Doe", "email": "john@example.com" },
    "group": { "title": "Cloud Certification", "key": "GcI6H5b66a3v", "code": "CC-2024" },
    "issued_on": "2024-03-15T10:30:00Z",
    "valid_until": null,
    "metadata": { "custom_location": "Mars" },
    "privacy": "public"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "success": false,
    "error": "Recipient Name and Email are required",
    "error_code": "missing_recipient"
  }
  ```

  ```json 402 Payment Required theme={null}
  {
    "success": false,
    "error": "Low balance",
    "error_code": "low_balance"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "success": false,
    "error": "Group Not Found",
    "error_code": "group_not_found"
  }
  ```

  ```json 409 Conflict theme={null}
  {
    "success": false,
    "error": "Credential already exists for this recipient, to overwrite, set duplication to true in group settings.",
    "error_code": "credential_exists"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "detail": "Invalid token or organization not found"
  }
  ```
</ResponseExample>

```bash theme={null}
curl -X POST "https://api.thehyperstack.com/v1/credentials/generate" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "group_key": "GcI6H5b66a3v",
    "custom_attributes": {
      "custom_location": "Mars"
    }
  }'
```