Generate an access token

Exchange your API key and secret for a gn-access-token that authenticates every other Genuin API request.

The Authentication API exchanges your brand's api_key and api_secret for a gn-access-token. Every other third-party endpoint, such as Create a community and Add members to a community, rejects requests that don't carry this token. Call this endpoint from your server, store the token it returns, and send that token as a bearer token on each subsequent request.

The token acts as your brand's owner account. Anything you do with it is done as that account.

Prerequisites

You need an api_key and an api_secret for your brand. The Genuin team issues one pair per brand: a 48-character hexadecimal key and a 32-character hexadecimal secret. Contact them to receive yours. The same pair works for every Authentication API call you make, and it works only while your brand is active.

Endpoint

POST /api/thirdparty/auth

This endpoint doesn't take an Authorization header. Your credentials go in the request body.

Parameters

Send both parameters as a JSON object in the request body with the Content-Type: application/json header. Without that header, the server doesn't parse the body and returns 412 Precondition Failed. The endpoint ignores any other field.

Returns

Returns 200 OK with the access token in the gn-access-token response header and a refresh token in the gn-refresh-token response header when both credentials match an active brand. Read both from the headers. The body confirms the result and identifies the brand owner account the token represents.

If either credential is missing, or the pair doesn't match an active brand, the endpoint returns an error instead. See Errors.

Request

curl -i -X POST https://api.begenuin.com/api/thirdparty/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "<<YOUR_API_KEY>>",
    "api_secret": "<<YOUR_API_SECRET>>"
  }'

The -i flag prints the response headers, which is where the tokens are.

Response

HTTP/1.1 200 OK
Content-Type: application/json
gn-access-token: {{GN_ACCESS_TOKEN}}
gn-refresh-token: {{GN_REFRESH_TOKEN}}

{
  "code": 200,
  "message": "Token Generated Successfully.",
  "data": {
    "user_id": "b12f13af-ef5a-4906-b0a0-2995e106200d",
    "login_source": "{{LOGIN_SOURCE}}",
    "device_type": null
  }
}

data.user_id is the UUID of your brand's owner account. data.login_source identifies the token as one issued by the Authentication API.

Token lifetime

Each call creates a new session. An access token stays valid for 14 days in production and 3 hours in QA; a refresh token stays valid for 100 days in production and 24 hours in QA. Generating a new token doesn't invalidate the tokens you already hold.

When an access token expires, every endpoint you call with it returns 401 Unauthorized. Either call this endpoint again, or exchange your refresh token for a new pair:

curl -i -X POST https://api.begenuin.com/api/v4/auth/session/refresh \
  -H "Authorization: Bearer {{GN_REFRESH_TOKEN}}"

The refresh response carries a new gn-access-token and a new gn-refresh-token in its headers. Don't send an x-brand-id header with this request. The refresh token is tied to your brand owner account, and a mismatched brand ID makes the call fail with 401.

Use the token

Pass the access token in the Authorization header of every other third-party API request, using the Bearer scheme:

curl -X POST https://api.begenuin.com/api/thirdparty/community/create \
  -H "Authorization: Bearer {{GN_ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "{{COMMUNITY_HANDLE}}",
    "name": "{{COMMUNITY_NAME}}"
  }'

If the header is missing, or the token is invalid, expired, or signed out, the endpoint you called returns 401 Unauthorized with code 1003 and the message authentication is required.. If the token has been altered, it returns 401 with code 5033. Generate or refresh a token and retry the request.

Rotate credentials

To replace a token you suspect has been exposed, call this endpoint again and switch your integration to the new value. The exposed token stays valid until it expires, so also contact the Genuin team if you need it revoked.

To replace the api_key and api_secret themselves, contact the Genuin team. Rotation is done on Genuin's side; there's no self-serve option in Brand Control Center. Your previous pair stops working as soon as the new one is issued.

Errors

Every error response has the same shape: an HTTP status, a string code, a message, and a data object.

{
  "code": "5235",
  "message": "Brand not exists.",
  "data": {}
}

The XXXX- prefix on some messages is literal. Match on code, not on message.

Limitations

• Rate limit: There's no rate limit on this endpoint.
• Test mode: There's no test credential pair for this endpoint. Use the QA base URL with the credentials issued for QA.

See also

• Create a community with the Create Community API
• Add members to a community with the Add Member API
• Create a group with the Create Group API
• How user authentication works in the Genuin SDK
• Handle API errors