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:
- Either use OAuth2 authorize code grant flow, as described above.
- 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 {}