Your first API request

The portal and API use the same subscription. Start with a read-only request. You need a RipsCloud account, an active workspace membership, and a personal access token (PAT).

Production has real effects

The production API sends health documents to DIAN and RIPS to FEV RIPS when you call emission or dispatch operations. This quickstart only reads data. Use a separate sandbox token and workspace for end-to-end tests.

1. Create a personal access token

1. Sign in to the RipsCloud production portal with your mobile phone and WhatsApp code.
2. Open Personal access tokens.
3. Give the token a name, select the workspace, select read, and set an expiry date.
4. Copy the secret when it is shown. You cannot view the secret again.

Keep the PAT on your server or in a secret manager. Do not put it in browser code, source control, screenshots, or request logs. Read the token guide.

2. Set your connection

export RIPSCLOUD_BASE_URL='https://api.ripscloud.com'
# Read the token without adding it to shell history.
read -rs RIPSCLOUD_TOKEN
export RIPSCLOUD_TOKEN

Paste the token at the prompt and press Enter. read -rs works in Bash and Zsh.

3. Check your identity

curl --fail-with-body "$RIPSCLOUD_BASE_URL/api/v1/me" \
  --header "Authorization: Bearer $RIPSCLOUD_TOKEN" \
  --header 'Accept: application/json'

A successful response is HTTP 200. The response identifies the user behind the token. Use the token as an opaque string; it is not a JWT.

4. Select a workspace

curl --fail-with-body "$RIPSCLOUD_BASE_URL/api/v1/me/workspaces" \
  --header "Authorization: Bearer $RIPSCLOUD_TOKEN" \
  --header 'Accept: application/json'

Read items and copy an authorized workspace id. Do not use a workspace ID from another account or environment.

export WORKSPACE_ID='replace-with-your-workspace-id'

5. Read your packages

curl --fail-with-body \
  "$RIPSCLOUD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/rips-packages?limit=20&offset=0" \
  --header "Authorization: Bearer $RIPSCLOUD_TOKEN" \
  --header 'Accept: application/json'

The list response contains items, total, limit, and offset. An empty list is valid. Keep the IDs exactly as returned.

Next steps

• Build the RIPS lifecycle to create, validate, and dispatch a package.
• Use a TypeScript or C# client for reusable request code.
• Browse the API reference for the exact parameters and response schemas.
• Handle errors and retries before you enable write operations.