Skip to content

Client tokens

Jump to bottom
Justin Forest edited this page Jan 24, 2023 · 13 revisions

Client tokens are OAuth access tokens that identify your application but not the user. With this token, you can access parts of the API that are not related to a particular user, such as searching for gifs, viewing gifs, accessing collections, etc. A client token can be obtained automatically without user interaction and is normally used before the user logs in. (After the user logs in, you use the user token instead.)

The token should be saved and used for all subsequent requests. We recommend requesting a new token about 10 minutes before the previous one expires.

Table of Contents:

Getting the token

To get a token, you send a request like this:

POST /v2/oauth/client HTTP/1.1
Host: api.redgifs.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=xxxxxxxxxx
&client_secret=xxxxxxxxxx

(For information on getting your client id and secret, see client credentials.)

Possible errors:

  • 401: unknown client id, possibly a typo.
  • 403: client disabled, please contact us.

A successful response will look like this:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
 
{
  "access_token": "your.secret.access.token",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "read"
}

You can then use the token to access all other parts of the API, for example:

GET /v2/gifs/search?order=trending&count=80 HTTP/1.1
Host: api.redgifs.com
Authorization: Bearer your.secret.access.token

Example using command line

$ curl -X POST 'https://api.redgifs.com/v2/oauth/client' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=xxxxxxxxxx' \
  -d 'client_secret=xxxxxxxxxx'
{"access_token":"your.secret.access.token","token_type":"Bearer","expires_in":86400,"scope":"read"}

Token life time

Tokens are issued for a limited time. Normally it is 24 hours, but can be changed for individual clients. When the token expires, it stops working and you need a new token. It's a good idea to track the expiration time (see expires_in in the response) and request a new token a few minutes before the current one expires.

Please save the tokens and reuse them, especially if you're building a server application. It's a bad idea to request a new token for every request. If that happens a lot, we might set a request rate limit for your client.

Clone this wiki locally