Skip to content

Authentication

The Nymbl API uses OAuth 2.0 client credentials flow for authentication. This ensures secure, token-based access to your data.

Getting Your Credentials

Contact your Nymbl account manager to receive:

  • Client ID: Your unique application identifier
  • Client Secret: Your secret key (keep this secure!)
  • Scope: Your authorized scope (e.g., nymbl-customer-api/acme-corp)

Requesting an Access Token

Token Endpoint

POST https://idp.api.nymbldev.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

Request Parameters

Parameter Value Description
grant_type client_credentials OAuth 2.0 grant type
client_id Your Client ID Identifies your application
client_secret Your Client Secret Authenticates your application
scope nymbl-customer-api/{customer} Your authorized scope

Example Request

curl -X POST https://idp.api.nymbldev.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=nymbl-customer-api/acme-corp"

Example Response

{
  "access_token": "eyJraWQiOiJ...",
  "expires_in": 300,
  "token_type": "Bearer"
}

Using the Access Token

All API requests require two headers: an OAuth 2.0 Bearer token and an API key.

Authorization: Bearer eyJraWQiOiJ...
x-api-key: YOUR_API_KEY

Example API Request

curl -X GET https://api.nymbldev.com/Patients \
  -H "Authorization: Bearer eyJraWQiOiJ..." \
  -H "x-api-key: YOUR_API_KEY"

Token Expiration

Access tokens expire after 5 minutes (300 seconds). Your application should:

  1. Cache the access token
  2. Monitor the expires_in value
  3. Request a new token before expiration
  4. Handle 401 Unauthorized responses by refreshing the token

Best Practices

Security Best Practices

  • Never commit client secrets to version control
  • Store credentials in environment variables or secret management systems
  • Use HTTPS for all requests
  • Implement token caching to avoid unnecessary token requests
  • Rotate client secrets periodically

Token Storage

Access tokens grant access to your data. Store them securely and never expose them in:

  • Client-side code
  • URL parameters
  • Logs or error messages
  • Public repositories

Troubleshooting

Invalid Client

If you receive an "invalid_client" error:

  • Verify your client ID and secret are correct
  • Ensure there are no extra spaces or newlines
  • Check that your credentials are for the correct environment

Invalid Scope

If you receive an "invalid_scope" error:

  • Verify your customer name is correct
  • Ensure the scope format is nymbl-customer-api/{customer}
  • Contact support if you need access to additional accounts

Unauthorized (401)

If you receive a 401 error on API requests:

  • Verify your access token is valid and not expired
  • Check that the Authorization header is properly formatted
  • Ensure you're using "Bearer" (not "bearer" or "BEARER")
  • Verify the x-api-key header is present and correct
  • Request a new access token