Skip to content

API authentication

The Minyu API uses Firebase-issued access tokens for authentication.

This authentication model is designed for:

  • server-to-server integrations
  • background jobs
  • external applications

Minyu does not issue long-lived API credentials directly. Instead, it establishes trust using a one-time setup token that is exchanged for Firebase tokens.

Authentication flow

API authentication follows this process:

  1. A system administrator generates a one-time setup token in Minyu.
  2. The external system exchanges this token with Firebase.
  3. Firebase returns:
  4. an access token (idToken)
  5. a refresh token
  6. The access token is used for API requests.
  7. The refresh token is used to obtain a new access token when needed.

Token types

The following token types are involved:

Token type Issued by Purpose Lifetime
Setup token Minyu Initial trust bootstrap Minutes
Access token (idToken) Firebase API authentication ~1 hour
Refresh token Firebase Renew access token Long-lived

Only the access token is sent with API requests.

Generate a setup token

To begin authentication:

  1. Open the Users / Integrations view in the Minyu administration interface.
  2. Locate the user or integration account.
  3. Click Generate API token.
  4. Copy the generated token.

Important:

  • the token is a one-time setup token
  • it cannot be used directly to call the API
  • it is only used to obtain Firebase tokens

Exchange the token with Firebase

The external system exchanges the setup token with Firebase to obtain an access token and refresh token.

Example request:

curl -X POST \
  "https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=YOUR_FIREBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "PASTE_TOKEN_FROM_MINYU",
    "returnSecureToken": true
  }'

Example response:

{
  "idToken": "FIREBASE_ACCESS_TOKEN",
  "refreshToken": "FIREBASE_REFRESH_TOKEN",
  "expiresIn": "3600"
}

Store both tokens securely.

Authenticate API requests

All API requests must include the Firebase access token as a bearer token.

Example:

curl -X POST https://api.minyu.com/graphql \
  -H "Authorization: Bearer FIREBASE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ health }" }'

Refresh the access token

Access tokens are short-lived and should be refreshed automatically by the client.

Example refresh request:

curl -X POST \
  "https://securetoken.googleapis.com/v1/token?key=YOUR_FIREBASE_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=PASTE_REFRESH_TOKEN"

Security considerations

  • The access token grants API access for the assigned tenant
  • Tokens must be stored securely
  • Setup tokens are single-use
  • If credentials are compromised, the related user or integration should be disabled in Minyu

How-to

Related concepts