Authorization

Authentication proves who you are. Authorization determines what you’re allowed to do. The External API enforces authorization at three levels:

1. Scope — does your token carry a scope the route requires?
2. Company access — is your application registered against the companyId in the URL?
3. Assigned user — for Supplier API calls, which E1 user’s data is returned?

All three must succeed for a request to return data.

Scopes

A scope is a named capability. The only partner scope defined today is:

Scope	Grants
speci-finder/read	Read Speci-finder matched projects for the registered supplier company.

When E1 provisions your application, it attaches a permission listing the scopes you’re allowed to use. At request time the API intersects:

• the scopes in your bearer token (see Authentication)
• with the scopes in your permission

and requires the route’s declared scope(s) to be present in the intersection. If not, the request fails with 401.

In practice:

• The route GET /api/supplier/v1/companies/{companyId}/speci-finder/results requires speci-finder/read.

Company access

The URL path includes a companyId. The API only answers the call if your application has a registration linking it to that company. Otherwise the request fails with 401.

Registrations are set up by E1 during onboarding, one per company. If you need to add another company, contact the onboarding team.

The assigned user (Supplier API)

Speci-finder keywords are configured on the supplier’s company account and apply account-wide — every user on that account shares the same keyword set. A Supplier API credential is bound at issuance to an assignedUserId, which identifies the account whose keywords drive matching.

• The API reads the assigned user from the credential and uses that user’s account keywords when forwarding the request to Ascension.
• You don’t pass the user ID in the request — it’s implicit in the credential.
• Because keywords are account-wide, any user on the same account resolves to the same set. To query a different supplier account, ask E1 to issue a credential bound to a user on that account.

What a failed authorization looks like

All authorization failures surface as 401 Unauthorised. See Errors for the specific error codes and their remediation.

Common causes:

• The scope requested on the token is not in the application’s permission, or the permission is not in published status.
• The companyId in the URL does not match any registration on the application.
• The x-e1-client-id header is missing or does not match the token (this one returns 400 or 401 with specific codes).