Data sources that are set to use the Dataspace verified API tokens access control mode will in each request coming from the product gateway on the dataspace receive an API token in the X-API-Key HTTP Header.

There are two ways a data source can verify this API token:

1. Validate the token as a JWT signed by the dataspace
2. Use the token verification endpoint on the product gateway

Validate token as a JWT signed by the dataspace

The API token is actually a JWT token signed by the dataspace and can easily be verified using most common JWT libraries.

As an example here’s a token that has been verified and decoded using the https://jwt.io service:

To verify the token you need to find the public keys of the dataspace. They can be found by checking the /.well-known/dataspace/dataspace-configuration.json on the base domain of the dataspace and locating the jwks_url. For example the dataspace configuration on ioxio.io points to https://ioxio.io/.well-known/jwks.json.

Things to ensure:

• The aud must match the DSI (Data Source Identifier) of your source. This is critical to verify! If you don’t verify this and someone else figures out the address at which your data source lives, they could publish it as their own data source on the same dataspace and grant access to it to anyone they want and get JWTs that are in all other aspects valid.
• The token is signed with one of the keys of the dataspace.
• The token hasn’t expired - make sure the exp is in the future and the iat is in the past (potentially allowing some reasonable leeway to account for clock differences, e.g. 5 minutes)
• The issuer (iss) is the base URL of the dataspace, for example https://ioxio.io, on which you’ve published the data source.

In case you want to do some more fine-grained access control to what data who has access to, you can use the sub to identify the group access was granted to.

An example implementation can be found on https://github.com/ioxio-dataspace/example-productizer/blob/3dd2435183ed5cbbd30c99a473a8d9c2ccf6b7c7/app/api_tokens.py#L221-L278

Token verification API

The product gateway offers an endpoint at the path /api/v1/api-token/verify. It expects a POST request with a body of the form:

{
  "aud": "dpp://group:[email protected]/Weather/Current/Metric_v1.0",
  "apiToken": "eyJ..."
}

The aud needs to match the DSI (Data Source Identifier) of the source you are providing, the apiToken is the token from the request that you want to verify is valid for your data source.