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:

• Request your token with scope=speci-finder/read (or omit scope to get everything your permission allows).
• 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 results are user-specific: the keywords that drive matching belong to an E1 user, not a company. So a Supplier API credential is bound at issuance to an assignedUserId.

• The API reads the assigned user from the credential and uses that user’s keywords when forwarding the request to Ascension.
• You don’t pass the user ID in the request — it’s implicit in the credential.
• If you need to query a different user’s keywords, ask E1 to issue a separate credential bound to that user.

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).