Access-Token

In order to perform any requests against the Webgate API you first need to authenticate using the Authorize Code Flow of the OAuth2 standard.

See http://tools.ietf.org/html/draft-ietf-oauth-v2-22#section-4.1 for the specification of the protocol.

All subsequent requests can be authorized using the access token which will be received via this protocol.

Registering a client

First, your client needs to be registered. For this, please send us your Redirection URI(s), and the name of your client. It is supposed to be easily recognized by webgate-users who are going to authorize your client. You will also need a webgate user to which the client will be bound to.
All the necessary data, like the client_id and secret_id, can be found within the menu "MyProfile", once your client has been registered to your user.
Also there, users can see all their authorized clients and revoke access grants at any time. In this case, the flow would have to be repeated.

Requesting an access token

There are two authentication flows:

  1. Either use OAuth2 authorize code grant flow, as described above.
  2. Or you can use the password grant flow:

Example:

POST /oauth/token HTTP/1.1
{
  "grant_type"    : "password",
  "username"      : "foobar@example.com",
  "password"      : "password"
}

Curl Example:

curl -X POST \
  https://webgate.io/oauth/token \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{ "grant_type": "password", "username": "foobar@example.com", "password": "yourpassword" }'

Successful Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "created_at" : 1507284619,
  "refresh_token" : "68ae2083c611bb45a2ac79d445e27c5852e7b1e0cb861a0c99172948dc73faa4",
  "access_token" : "63fcc7dbbfd71a9677d8e66623500c03d1d69ed512ac0888573794a3e1820d91",
  "expires_in" : 79427,
  "user" : {
    "id" : 123,
    "name" : "John Doe",
    "email": "john@doe.com"
  },
  "token_type" : "bearer"
}

Response when login failed (first 3 attempts):

HTTP/1.1 200 OK
Content-Type: application/json

{
    "error": "invalid_grant",
    "error_description": "The username and password you entered did not match our data."
}

Response when login failed (user is locked after 3 attempts):

HTTP/1.1 200 OK
Content-Type: application/json

{
    "error": "locked_user",
    "error_description": "Your account is temporarily locked.",
    "state": "Your account has been disabled! (More than 3 failed login attempts.) Please try again in less than 10 seconds ..."
}

Validity

A token expires after 24 hours. If the user hasn't revoked the authorization, a new token can be generated at any time. Your application should do this automatically.

Invalidating an access token

Tokens can be invalidated.
To do this, send a POST request to /oauth/revoke. The request needs to carry the access token, of course.

Example:

POST /oauth/revoke HTTP/1.1
Authorization: Bearer example-token

Successful Response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

Authorization

Once an access token has been obtained by the client, it can be used to request resources that the authenticated user is allowed to access.

NOTE: client applications MUST expect a request to fail due to insufficient authorization at any point. The fact that a resource can be seen in a listing doesn't always indicate that it can be accessed, as it may have been deleted in the meantime.

Passing the access token via an HTTP header

The preferred way of passing the token is by setting the Authorization header, using the Bearer authorization scheme and the access token.

NOTE: Client application developers should take special care using this method, so the access token will NOT show up in logfiles and won't be exposed in any other way. Since the URI is not encrypted, every attempt to send the token over the URI will fail, and the token will be invalidated. Please always sent the token with the encrypted headers.

Example:

GET /api/projects HTTP/1.1
Authorization: Bearer example-token

Example:

GET /api/projects

Handling authorization failures

Whenever a protected resource is requested, the authorization may fail.
In general there are three distinct cases that cause this to happen:

  1. No access token was provided
  2. The provided access token is invalid
  3. The accessed resource may not be accessed by the user associated with the access token

The former two cases cause an equivalent 401 (Unauthorized) response, while the latter causes a 403 (Forbidden) response.

401 example response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "status": 401,
  "status_message": "Unauthorized",
  "error": "Token missing, invalid, or expired. Token expires after 24 hours of idle time."
}
NOTE: If a client application receives this response even though it passed a (thought to be) valid access token, it SHOULD take steps to acquire a new access token.

403 example response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "status": 403,
  "status_message": "Forbidden",
  "error": "Forbidden"
}