Skip to main content

Understanding API Scopes

A quick guide to what scopes are, and why your credentials are set up the way they are​

If you've ever gotten an invalid_scope error while setting up your integration, this article will help you understand what's happening and how to fix it.

What is a "scope," in plain terms?​

Think of your API credentials (your client ID and client secret) as a keycard. A scope is what that keycard has been programmed to unlock. It's not something you choose on the fly, it's a permission that Honeybee Health sets on our end, tied to your specific credentials, before you ever start integrating.

In other words: your credentials will only work for the systems they've been granted access to. If you try to use them somewhere they haven't been set up for, you'll get an error. This isn't because you did something wrong, but because that door hasn't been unlocked for that keycard yet.

The two scopes you'll encounter​

Honeybee Health has two main systems, and each one has its own scope. Most organizations only need one.

partners

Used by partner organizations. This is what powers order management, shipment tracking, and webhook notifications. If your team is managing orders, prescription status, or patient fulfillment data, this is the scope for you.

nectar

Used by e-prescribing vendors. This is what powers sending electronic prescriptions to Honeybee Health for fulfillment. If your organization is the one prescribing (not managing downstream orders), this is the scope you'll be issued.

Most credentials are set up with just one of these. If your organization needs both (for example, you both e-prescribe and manage your own orders), a single set of credentials can be granted both scopes.

Requesting an access token​

When your system asks Honeybee Health for an access token, it can include a scope field to specify which system it's trying to reach.

A couple of things worth knowing:

  • If you're using Nectar credentials, send scope=nectar.
  • If you're using Partners API credentials, whether to send a scope depends on how the credentials were created:
    • Credentials you create in the partner dashboard have the partners scope assigned. Send scope=partners on every token request. Leaving the field out resolves to an empty scope set and returns the same invalid_scope error as requesting a scope you don't have.
    • Credentials issued to you before the dashboard assigned scopes have no scope on them. Leave the scope field out. Sending scope=partners on one of these also returns invalid_scope, because that scope was never granted on the credential.
  • If your credentials have been granted both nectar and partners, request whichever one you need for that token: send scope=nectar to reach Nectar, or scope=partners for the Partners API. A given token still carries only the one scope you requested, never both at once.
  • Never send scope=none as a literal value. It isn't a valid placeholder and fails the same way.

Moving to scoped credentials​

If you have an older credential with no scope assigned and you want a scoped setup, the path is to rotate credentials. You do this yourself in the partner dashboard:

  1. Generate a new credential in the dashboard. It includes the partners scope automatically.
  2. Update your integration to the new client ID and secret, and include scope=partners in your token requests.
  3. Deactivate the old credential once you have cut over. Access tokens already issued to the old credential keep working until they expire, up to 12 hours.

Do not add scope=partners to token requests for an older credential. A credential with no scope assigned rejects scoped requests with invalid_scope. Rotating to a new dashboard credential is the self-serve way onto scopes for an older credential.

Troubleshooting: "invalid_scope" errors​

If you see a response like this:

{"error":"invalid_scope","error_description":"The requested scope is invalid, unknown, or malformed."}

it almost always means one of the following:

  • You're requesting a scope your credentials haven't been granted (for example, requesting nectar with Partners API credentials, or vice versa)
  • You left the scope field out, but your credentials have a scope assigned. Dashboard-created credentials have partners, so send scope=partners.
  • You sent scope=partners, but your credentials have no scope assigned. Older credentials issued before the dashboard assigned scopes reject scoped requests. Omit the scope field, or rotate to a new dashboard credential to use scopes (see "Moving to scoped credentials" above).
  • You're sending a placeholder value like none
  • There's a typo in the scope value itself

Still stuck? Reach out to your Honeybee partner success contact with the client ID you're using (never share your client secret) and the exact request you're sending. We can confirm which scope your credentials are set up for and get things unblocked quickly.

A note on Sandbox testing​

Our Sandbox environment doesn't always mirror production scope setups one-to-one. If your organization has multiple credential sets in production (for example, one for Nectar and one for Partners API), Sandbox may require you to test each one separately rather than in the exact same combined setup you'll use live. If your Sandbox testing behaves differently than expected, this is a common and expected reason, not a sign that something's broken.