---
title: Elosung API authentication
description: Bearer API key authentication, scopes, safe retries and access boundaries for Elosung Affiliate Agent interfaces.
canonical: https://elosung.cn/auth.md
last-updated: 2026-08-21
---

# Elosung API authentication

Elosung's Affiliate REST API and MCP tools use an owner-issued opaque Bearer API key. Public documentation, the OpenAPI description, the MCP status document and the Agent Card do not require a credential.

## Obtain a key

1. Create or sign in to an Elosung Promoter account.
2. Complete the promoter access review.
3. Open the promoter workspace and create an Agent API key.
4. Copy the key once and store it in a secret manager as `ELOSUNG_API_KEY`.

Keys belong to the verified human promoter. They cannot transfer commission ownership or bypass buyer review.

## Send a request

```http
Authorization: Bearer $ELOSUNG_API_KEY
Content-Type: application/json
```

Never place a key in a URL, browser query string, source repository or client-side bundle.

## Available scopes

- `products:read` — search the published ready-stock catalog.
- `links:write` — create attributed catalog or product links.
- `handoffs:write` — prepare a buyer-reviewed product handoff; it does not submit an RFQ.
- `leads:read` and `leads:write` — manage only the promoter owner's attributed leads.
- `performance:read` — read the same Agent identity's attributed performance.
- `social:write` — prepare or report an owner-controlled social publishing task.
- `messages:write` — send only an outreach message already approved by an Elosung administrator.
- `agents:notify` — notify an owner-allowlisted Agent connector.

Call `GET /api/affiliate/v1/connection` or the MCP `get_connection` tool to inspect the scopes actually granted to a key.

## Safe retries

Every write requires an `Idempotency-Key`. Reuse the same key only for an exact retry of the same input. A changed payload requires a new key.

## Errors and recovery

REST failures return structured JSON with a stable code, message and request ID. A missing or invalid credential returns HTTP 401 with a Bearer challenge. Unknown v1 routes return `application/problem+json` with links to the OpenAPI description and developer portal.

## Human approval boundaries

The public Agent interfaces do not accept quotations, submit buyer RFQs, place orders or send payment. The buyer controls procurement-list review and RFQ submission; Elosung staff control quotation, allocation and fulfillment decisions.

## Related resources

- Developer portal: https://elosung.cn/developers
- OpenAPI 3.1: https://elosung.cn/api/affiliate/openapi.json
- MCP endpoint: https://elosung.cn/api/affiliate/mcp
- Agent Card: https://elosung.cn/.well-known/agent-card.json