Authentication

The Vinix Core API uses token-based authentication. Every request must include an X-Auth-Token HTTP header:

curl https://api.vinixglobal.com/v2/accounts/$ACCOUNT_ID \
  -H "X-Auth-Token: $VINIX_AUTH_TOKEN"

Tokens are short-lived (~1 hour by default). You generate them one of two ways:

1. User auth — hash a user's password and trade for a token. Best for UI applications, interactive scripts, and one-off curl experiments.
2. API-key auth — get a long-lived API key for an account, then trade that key for tokens on-demand from a backend service. Best for server-to-server integrations.

User auth — credentials → token

You need three things:

1. A user identifier for one of the account name (account_name), the account realm (account_realm), or a phone number assigned to the user (phone_number).
2. A credentials hash — MD5 (or SHA-1) of username:password. The username must be lowercased before hashing.
3. A method of "md5" (default) or "sha".

Step 1 — compute the credentials hash

# MD5 (default)
echo -n '[email protected]:m32c6NfqYEt' | md5sum
# 82a2dc91686ec828a67152d45a5c5ef7

# SHA-1
echo -n '[email protected]:m32c6NfqYEt' | shasum
# 055cf886cb9b5c5867083463867c527ace0f8ecc

The colon between username and password is part of the input.

Step 2 — request a token

curl -X PUT https://api.vinixglobal.com/v2/user_auth \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "credentials": "82a2dc91686ec828a67152d45a5c5ef7",
          "account_name": "acme-telecom",
          "method": "md5"
        }
      }'

Successful response:

{
  "auth_token": "abc123...",
  "data": {
    "account_id": "1f9a8b2c-3d4e-4f50-91a2-7b8c9d0e1f23",
    "owner_id": "...",
    "language": "en-US",
    "is_reseller": true
  },
  "request_id": "req_01HM...",
  "status": "success"
}

Use the returned auth_token as X-Auth-Token on subsequent requests.

API-key auth — for server-to-server

User auth requires a password. For backend integrations, prefer the account-level API key: a long-lived secret tied to an account that you swap for short-lived tokens.

Step 1 — fetch the API key (one-time)

Authenticate as an admin user first, then:

curl https://api.vinixglobal.com/v2/accounts/$ACCOUNT_ID/api_key \
  -H "X-Auth-Token: $USER_AUTH_TOKEN"

{
  "data": { "api_key": "vinix_key_..." },
  "status": "success"
}

Store the api_key in your secrets manager. You can rotate it from the dashboard or via POST /accounts/{id}/api_key; you don't need the user password again.

Step 2 — trade the API key for a token

curl -X PUT https://api.vinixglobal.com/v2/api_auth \
  -H "Content-Type: application/json" \
  -d '{ "data": { "api_key": "'"$VINIX_API_KEY"'" } }'

Response shape matches user_auth — same auth_token to use against the rest of the API.

Backend pattern: cache the token for ~50 minutes (under the ~1-hour TTL), refresh on a 401, retry once.

Basic auth (discouraged)

For terminal experiments, the API also accepts HTTP Basic with a specific value format (base64(account_id:md5(user:pass))). Don't use this from anything that logs requests — credentials end up in every log line.

Token lifecycle

Sandbox vs. production

Both environments use the same auth flow — sandbox is a separate account, so its user_auth credentials and API key are distinct from production.

Rotation

• User passwords — change via PATCH /accounts/{id}/users/{user_id} or through the dashboard. All tokens minted from the old password invalidate.
• Account API key — rotate via POST /accounts/{id}/api_key. The old key stops trading for tokens immediately.

Best practice: rotate the account API key at least once per quarter, and immediately on suspected compromise.