A WimTV API can be public or private.

The public APIs (path /api/public/…​) can access only the public data.
If you want to use a public API, you should request a public access token through by the client credentials (the client id and eventually the client secret).

The private APIs (path /api/…​) can access the private data of a specific user.
If you want to use a private API, you should request a private access token through by the client credentials and also the user credentials (the user name and the password).

Gets a public access token

You can use a public access token to call a public API.

$ curl 'http://www.wim.tv:8080/oauth/token' -i -u 'test:test_api' -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: application/json' -d 'grant_type=client_credentials'

Request headers

Name Description

Authorization

Basic auth credentials of the client.

Request parameters

Parameter Description

grant_type

Must be client_credentials.

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Content-Length: 127

{
  "access_token" : "853288d2-a75f-4141-a7ec-db0c151414df",
  "token_type" : "bearer",
  "expires_in" : 4,
  "scope" : "all"
}

Response fields

Path Type Description

access_token

String

Access token.

token_type

String

bearer

expires_in

Number

Validity of the access token (seconds).

scope

String

all

Gets a private access token

You can use a private access token to call a public or private API.

$ curl 'http://www.wim.tv:8080/oauth/token' -i -u 'test:test_api' -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: application/json' -d 'username=john&password=secr3t&grant_type=password'

Request headers

Name Description

Authorization

Basic auth credentials of the client.

Request parameters

Parameter Description

username

Name of the user.

password

Password of the user.

grant_type

Must be password.

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Content-Length: 187

{
  "access_token" : "2a4cf032-fa2d-4f53-84ed-99e9a916b3a2",
  "token_type" : "bearer",
  "refresh_token" : "032a038a-f1eb-4ca7-bd0a-e7f1fafef630",
  "expires_in" : 4,
  "scope" : "all"
}

Response fields

Path Type Description

access_token

String

Access token.

refresh_token

String

Refresh token.

token_type

String

bearer

expires_in

Number

Validity of the access token (seconds).

scope

String

all

Expired access token

When your access token expires, the API fails.

When you request a private access token, you get also a refresh token: when the access token expires, you should refresh it using the refresh token.

Response

HTTP/1.1 401 Unauthorized
Cache-Control: no-store
Pragma: no-cache
WWW-Authenticate: Bearer realm="oauth2-resource", error="invalid_token", error_description="Access token expired: 853288d2-a75f-4141-a7ec-db0c151414df"
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Content-Length: 117

{
  "error" : "invalid_token",
  "error_description" : "Access token expired: 853288d2-a75f-4141-a7ec-db0c151414df"
}

Refreshes a private access token

When your private access token expires, you should use the refresh token to request a new private access token.

$ curl 'http://www.wim.tv:8080/oauth/token' -i -u 'test:test_api' -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: application/json' -d 'grant_type=refresh_token&refresh_token=032a038a-f1eb-4ca7-bd0a-e7f1fafef630'

Request headers

Name Description

Authorization

Basic auth credentials of the client.

Request parameters

Parameter Description

grant_type

Must be refresh_token.

refresh_token

The refresh token.

Using the refresh token you avoid to transmit the user credentials and this is good for security.

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Content-Length: 187

{
  "access_token" : "441471ee-2907-4699-bf7d-c7de29b48867",
  "token_type" : "bearer",
  "refresh_token" : "032a038a-f1eb-4ca7-bd0a-e7f1fafef630",
  "expires_in" : 4,
  "scope" : "all"
}

Response fields

Path Type Description

access_token

String

Access token.

refresh_token

String

Refresh token.

token_type

String

bearer

expires_in

Number

Validity of the access token (seconds).

scope

String

all

The current OAUTH2 implementation may generate only a new access token and keep the same refresh token, but you should not rely on this behavior: the implementation could be changed.

Expired refresh token

When your refresh token expires, you should request another private access token.

Response

HTTP/1.1 401 Unauthorized
Cache-Control: no-store
Pragma: no-cache
WWW-Authenticate: Bearer error="invalid_token", error_description="Invalid refresh token (expired): 032a038a-f1eb-4ca7-bd0a-e7f1fafef630"
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Content-Length: 128

{
  "error" : "invalid_token",
  "error_description" : "Invalid refresh token (expired): 032a038a-f1eb-4ca7-bd0a-e7f1fafef630"
}

Calling an API without an access token

If you try to call an API without an access token, the API fails.

Response

HTTP/1.1 401 Unauthorized
Cache-Control: no-store
Pragma: no-cache
WWW-Authenticate: Bearer realm="oauth2-resource", error="unauthorized", error_description="Full authentication is required to access this resource"
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Content-Length: 113

{
  "error" : "unauthorized",
  "error_description" : "Full authentication is required to access this resource"
}

Calling a private API with a public access token

If you try to call a private API with a public access token, the API fails.

Response

HTTP/1.1 403 Forbidden
Cache-Control: no-store
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Content-Length: 75

{
  "error" : "access_denied",
  "error_description" : "Access is denied"
}

Bad client credentials

If you request an access token with bad client credentials, the API fails.

Response

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="oauth2/client"
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

{
  "timestamp" : "1474095055437",
  "status" : 401,
  "error" : "Unauthorized",
  "message" : "Bad credentials",
  "path" : "/wimtv-server/oauth/token"
}

Bad user credentials

If you request an access token with bad user credentials, the API fails.

Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Content-Length: 74

{
  "error" : "invalid_grant",
  "error_description" : "Bad credentials"
}

Invalid access token

If you use an invalid access token (or retry to use an expired access token), the API fails.

Response

HTTP/1.1 401 Unauthorized
Cache-Control: no-store
Pragma: no-cache
WWW-Authenticate: Bearer realm="oauth2-resource", error="invalid_token", error_description="Invalid access token: 853288d2-a75f-4141-a7ec-db0c151414df"
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Content-Length: 117

{
  "error" : "invalid_token",
  "error_description" : "Invalid access token: 853288d2-a75f-4141-a7ec-db0c151414df"
}

Invalid refresh token

If you use an invalid refresh token (or retry to use an expired refresh token), the API fails.

Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Content-Length: 118

{
  "error" : "invalid_grant",
  "error_description" : "Invalid refresh token: 032a038a-f1eb-4ca7-bd0a-e7f1fafef630"
}