Authentication

As an admin user for your organization, you can manage your API keys in the Command Center. We recommend adding a sandbox API key for each developer working on the integration. Each developer should securely save a respective key’s CLIENT_ID and CLIENT_SECRET. Later, when moving to production, create a separate API key with live-only permission. Save this key’s CLIENT_ID and CLIENT_SECRET securely in your own production environment to interact with the Noyo API.

Once you have an API key, you can generate a short-lived access token (valid for 10 minutes) using the CLIENT_ID and CLIENT_SECRET as the username/password combination in a Basic Authentication header.

Use the following curl snippet directly, or import it into API client software such as Postman:

curl -X POST
 --header "Content-Type: application/json"
 --header "Authorization: Basic <Base64Encode(<CLIENT_ID>:<CLIENT_SECRET>)>"
 --data '{"grant_type": "client_credentials"}'
 https://accounts.noyo.com/auth/public/token

The response will include your ACCESS_TOKEN:

{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": 864000,
  "token_type": "Bearer"
}

Use this ACCESS_TOKEN in the Authorization header for each request you make to the Noyo API, like this request to get a list of groups for your organization in the sandbox:

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment-sandbox.noyo.com/api/v1/groups

You can make this request to test whether your token is working correctly. At this stage, you should have a sandbox group configured, which will be returned in this API result. You should get a 200 response to confirm a successful call:

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 1
    },
    "response": [{
        "id": "5d0b974b-2ee1-4d42-bf81-6715079b6a29",
        "version": "e3d63d18-b210-450a-bdda-fadba098e9c2",
        "created": 1631553366,
        "modified": 1631553366,
        "organization_id": "95e591f8-102d-4df9-8e9f-24e5c9b77d56",
        "name": "Your Sandbox Group Name",
        "sic_code": "",
        "dba_name": "",
        "federal_ein": ""
    }]
}

Authentication troubleshooting

For most authentication issues you will receive one of the following error messages. For any other issues, contact [email protected].

Missing credentials

A JWT has not been supplied in the Authorization HTTP header. Ensure that the Authorization HTTP header reads Bearer <JWT>.

401 Unauthorized

{
    "code": 16,
    "message": "JWT validation failed: Missing or invalid credentials",
    "details": [
        {
            "@type": "type.googleapis.com/google.rpc.DebugInfo",
            "stackEntries": [],
            "detail": "auth"
        }
    ]
}

Malformed JWT

The JWT has been truncated or altered in some way since it was originally acquired. Please double check the original HTTP response from https://accounts.noyo.com/auth/public/token.

401 Unauthorized

{
   "code": 16,
   "message": "JWT validation failed: The JWT cannot be validated with any of the public keys.",
   "details": [
       {
           "@type": "type.googleapis.com/google.rpc.DebugInfo",
           "stackEntries": [],
           "detail": "auth"
       }
   ]
}

Expired token

The JWT has expired. We recommend requesting a new API token and re-attempting your original request. You can anticipate this issue by using the expires_in property returned along with any API token. The expires_in value is the number of milliseconds until the API token expires. A token refresh performed before that time could mitigate this issue.

401 Unauthorized

{
    "code": 16,
    "message": "JWT validation failed: TIME_CONSTRAINT_FAILURE",
    "details": [
        {
            "@type": "type.googleapis.com/google.rpc.DebugInfo",
            "stackEntries": [],
            "detail": "auth"
        }
    ]
}