Logging in

The login-flow is as defined by the OAuth 2 framework (actually, OpenID Connect). Clients use the Client Credentials Grant flow. Clients can log in on behalf of a user using the Authorization Code Grant flow.

Looking at the root-resource, you’ll find the link OpenID Connect issuer link pointing to the identity provider.

$ curl https://api.goabout.com
{
  "_links" : {
    "http://openid.net/specs/connect/1.0/issuer": {
        "href": "https://goabout.eu.auth0.com"
    },
    [...]
  }
  [...]
}

Following the discovery protocol, the issuer configuration is found at /.well-known/openid-configuration. It contains the token, and authorization endpoints, which you can use to authorize Users and retrieve Bearer Tokens for both Clients and Users.

$ curl https://goabout.eu.auth0.com/.well-known/openid-configuration
{
  "authorization_endpoint": "https://goabout.eu.auth0.com/authorize",
  "token_endpoint": "https://goabout.eu.auth0.com/oauth/token",
  [...]
}

Logging in with client-credentials

Some resources require client-authentication (or higher). The Geocoder resource is an example. To authenticate yourself with the API, you’ll need a Bearer token that was obtained using the client credentials grant type.

You need to specify an extra non-standard parameter audience that must be set to https://api.goabout.com.

$ curl 'https://goabout.eu.auth0.com/oauth/token' \
    -H'Content-Type: application/json' \
    -d '{
          "grant_type": "client_credentials",
          "audience": "https://api.goabout.com",
          "client_id": "CLIENT-IDENTIFIER",
          "client_secret": "CLIENT-SECRET"
        }'
{
  "access_token": "ACCESS-TOKEN",
  "expires_in": 604800,
  "token_type": "Bearer"
}

Using the token

You send the token along with every request, using the Authorization header.

$ curl -H'Authorization: Bearer TOKEN' [URL]

With a client-token (i.e. a Bearer token received with client credentials), follow any of the linked resources are available to you as a client.

$ curl -s -H 'Authorization: Bearer TOKEN' https://api.goabout.com
{
  "version": "x.y.z",
  "_links": {
    "self": {
      "href": "https://api.goabout.com/"
    },
    "http://rels.goabout.com/plan": {
      "href": "https://api.goabout.com/plan"
    },
    "http://rels.goabout.com/geocoder": {
      "href": "https://api.goabout.com/geocoder/encode{?query,count}",
      "templated": true
    },
    [...]
  }
}