backend

V1 API

This is the V1 API

In charge of

• routing requests to the correct service
• API keys lifecycle management
• blocking requests (if insufficient privilege or some other reason).

Quickstart

Generating and using an API key

1. Sign up for an account
2. Generate a key where your auth token can be found via micro user token

 curl https://api.m3o.com/v1/api/keys/generate -d '{"scopes":["location:write"], "description":"my first token"}' -H "Content-Type: application/json" -H "Micro-Namespace: micro" -H "Authorization: Bearer <your auth token>" 

Your response should look like

{"apiKey":"ZDIxYTJhMDctZjgwMC00YmJhLTk0YTItOTAxOWJlMTU2OWU5"}

1. Pass this API key on subsequent calls

curl https://api.m3o.com/v1/helloworld/call  -H "Authorization: Bearer ZDIxYTJhMDctZjgwMC00YmJhLTk0YTItOTAxOWJlMTU2OWU5" -H "Content-Type: application/json" -d '{"name":"Dom"}'

{"msg":"Hello Dom"}                       

Listing keys

 curl https://api.m3o.com/v1/api/keys/list -H "Content-Type: application/json" -H "Micro-Namespace: micro" -H "Authorization: Bearer <your auth token>" 

Delete a key

 curl https://api.m3o.com/v1/api/keys/revoke -d '{"id":"<api key id from the listkeys call>"}' -H "Content-Type: application/json" -H "Micro-Namespace: micro" -H "Authorization: Bearer <your auth token>" 

Design

Key format

The API key is an opaque base64 encoded token e.g. ZDIxYTJhMDctZjgwMC00YmJhLTk0YTItOTAxOWJlMTU2OWU5. It should have no value to anyone in terms of inspecting it and should mean that any leaked keys are only useful if the person who finds them knows that it's related to the micro platform.

Routing

Routing logic is based on the url path and is currently very simple.

• /v1/foo/bar/{alpha, bravo, ...} routes to foo service Bar.Alpha endpoint
• /v1/helloworld/call routes to helloworld service Helloworld.Call endpoint

Key lifecycle

1. A key can be generated by calling the GenerateKey endpoint. It takes a list of scopes and a description. The description is the only way that the user will be able to discern what the key is for - e.g. when they view a list of their keys (similar to how things like GitHub work). API key starts in blocked status so all requests will be blocked until further processing is done in the background (see below). Importantly, only a hash of the API key is ever stored - we never store the key itself so if the user loses it they need to generate a new one.
2. A new auth account is generated for the API key under the user's namespace with the specified scopes. The account will be of type apikey. Creating a separate account means that we can track the usage of this API key at a finer granularity if we wanted to. We add a metadata entry of apikey_owner which specifies the account ID that created the key.
3. Once the key is created we publish an event for API key creation
4. Something (Quota service) picks up the event and works out which endpoints should be unblocked for the API key; calls UpdateAllowedPaths to unblock the user for the relevant urls
5. The key is now ready to be used for requests (the above happens async but should be as close to instantaneous as makes no difference)

Using the key

1. API key passed in on request as Authorization: Bearer <key>
2. The micro API service can't decode the key as a JWT so will forward to the micro namespace by default
3. v1 service verifies the key by looking up the hash
4. If we recognise it we grab a valid JWT token for the account; either we have a short lived one cached or we generate a new JWT token (the API key is actually the password for the account). Note: the JWT tokens are short lived (1 hour) but if the DB was ever breached you could in theory get a token that has validity for up to an hour to impersonate the victim (we can always shorten this timespan if required).
5. We then forward the request, adding the JWT token to the request context as the bearer token

Blocking requests

If requests for a client need to be blocked (insufficient privilege or exhausted quota) we call UpdateAllowedPaths and update the allowed paths for the user as a whole (which has the effect of just updating all their API keys).

The same happens for unblocking requests.

Scopes

Scopes define what an API key can do.

Proposal: By convention scope names could implicitly define which endpoints the client has access to. So location:write means they have access to all endpoints as defined by the location service.

Setup

When running the v1 api you'll need to setup auth rules so that users can call it appropriately

Base

At a minimum you need to run the following

micro auth create rule --resource="service:v1:V1.Endpoint" --priority 1 v1-endpoint-public
micro auth create rule --resource="service:v1.api:Keys.Generate" --priority 1 v1-generatekey-public
micro auth create rule --resource="service:v1:V1.GenerateKey" --priority 1 --scope '+' v1-generatekey2-public
micro auth create rule --resource="service:v1.api:Keys.List" --priority 1 v1-listkeys-public
micro auth create rule --resource="service:v1:V1.ListKeys" --priority 1 --scope '+' v1-listkeys2-public
micro auth create rule --resource="service:v1.api:Keys.Revoke" --priority 1 v1-revokekey-public
micro auth create rule --resource="service:v1:V1.RevokeKey" --priority 1 --scope '+' v1-revokekey2-public
micro auth create rule --resource="service:v1.api:Apis.List" --priority 1 v1-listapis-public
micro auth create rule --resource="service:v1:V1.ListAPIs" --priority 1 --scope '+' v1-listapis2-public 
 

This allows users to hit the core v1 endpoints.

Adding a new API

To add a new API you should call the EnableAPI endpoint which will add the relevant auth rules and ensure it shows up in the list of available APIs. You will also need to add at least one quota to allow users to call the API.

micro call v1 V1.EnableAPI '{"name":"foobar"}'
micro call quota Quota.Create '{"quota":{"id":"foobar_free", "limit":10, "reset_frequency":"DAILY", "path":"/foobar/"}}'