Authentication

This page explains how to authenticate your requests to the pycli HTTP API. Every request you send to the API must be authenticated so the service can verify your identity and authorize your actions. Without valid credentials, your requests will be rejected before any order or configuration logic runs. Understanding authentication is the essential first step before you can create orders, list them, or cancel them.

Before following the steps on this page, make sure you have:

• pycli installed on your machine (see the Installation guide)
• curl or an HTTP client of your choice (examples on this page use curl)
• An active pycli account with API access enabled
• Your API credentials — retrieve these from your account dashboard before continuing

pycli is distributed as a Python package. Follow these steps to install it:

1. Ensure Python is available on your system.

   Copy

   python --version
   

2. Install pycli using pip.

   Copy

   pip install pycli
   

3. Verify the installation succeeded.

   Copy

   pycli --version
   

After installation, configure your credentials so the CLI and HTTP client can authenticate automatically.

Set these as environment variables in your shell so you do not have to repeat them on every command:

export PYCLI_API_KEY="your-api-key-here"
export PYCLI_API_BASE_URL="https://api.example.com"

Alternatively, place them in a .env file at the root of your project if your tooling supports automatic loading.

Once your credentials are configured, include them on every request you make to the pycli API. The API base URL for all endpoints is:

https://api.example.com

The following endpoints require authentication:

Pass your API key in the request header on every call. For example, to fetch order 42:

curl https://api.example.com/orders/42 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Replace YOUR_API_KEY with the value of your PYCLI_API_KEY. If the key is missing or invalid, the server returns an error response and your request is not processed.

The following examples show authenticated requests against the pycli API. Each request includes the required credential header.

Create an order

curl -X POST https://api.example.com/orders \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"amount": 1500, "currency": "USD"}'

Expected response:

{
  "id": 1,
  "amount": 1500,
  "currency": "USD",
  "status": "pending"
}

List paid orders

curl 'https://api.example.com/orders?status=paid&limit=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Expected response:

{
  "status": "paid",
  "limit": 10,
  "orders": []
}

Fetch a single order

curl https://api.example.com/orders/42 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Expected response:

{
  "id": 42,
  "amount": 100,
  "currency": "USD",
  "status": "paid"
}

Cancel an order

curl -X DELETE https://api.example.com/orders/42 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Expected response:

{
  "id": 42,
  "status": "canceled"
}

Use the following reference when your authenticated requests are not behaving as expected.

Symptom: Every request returns a 401 Unauthorized response.

Likely cause: Your API key is missing from the request, has been entered incorrectly, or has expired.

Fix: Double-check that you are including the credential header on every request and that the key value matches exactly what was issued to your account. Re-export your environment variable and retry:

export PYCLI_API_KEY="your-correct-api-key"
curl https://api.example.com/orders/42 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Symptom: Every request returns a 403 Forbidden response.

Likely cause: Your API key is valid but your account does not have permission to perform the requested action (for example, your key may have read-only scope and you are attempting a DELETE).

Fix: Check the scopes or permissions associated with your API key in your account dashboard. If you need broader access, generate a new key with the appropriate permissions.

Symptom: Requests succeed in your browser or with other tools but fail when using curl.

Likely cause: The credential header is not being passed correctly — this often happens when shell quoting causes the header value to be malformed.

Fix: Ensure single quotes wrap the entire header value and that there are no extra spaces around the colon:

# Correct
-H 'Authorization: Bearer YOUR_API_KEY'

# Incorrect — extra space or mismatched quotes can break parsing
-H "Authorization:Bearer YOUR_API_KEY"

Symptom: The CLI commands work but direct curl requests to the API return authentication errors.

Likely cause: The CLI may be reading credentials from a different source (e.g., a config file or keychain) that your raw curl commands are not replicating.

Fix: Inspect the headers the CLI sends (add --verbose or -v to your curl command) and replicate them exactly in your manual requests.