Authentication

Creating and Updating your Application

You can create an application in the Gravatar Developer Dashboard. Afterward, navigate to the application’s settings and fill in all the fields. Note: We don’t force you to fill in all the fields, but you will need all of them to get your access token properly.

Redirect users to the authorization endpoint

To act on a user’s behalf and make calls from our API you will need an access token. To get an access token you need to go through the access token flow and prompt the user to authorize your application to act on their behalf.

To begin, you will need to redirect the user to the authorization endpoint, https://public-api.wordpress.com/oauth2/authorize

Parameters

For the user to properly authorize your app, you’ll need to provide us with the following parameters in the request. Remember, all parameters should be URL-encoded:

• client_id should be set to your application’s client ID as found in the application settings.
• redirect_uri should be set to the URL the user will be redirected to after the request is authorized. The URL must match one of the URLs you defined in the application settings.
• response_type can be code or token.
  • Code should be used for server-side applications where you can guarantee that secrets will be stored securely. These tokens do not expire.
  • Tokens should be used for client-side applications. This is called “Implicit OAuth.”  Tokens currently last two weeks, and users will need to authenticate with your app once they expire. Tokens are returned via the hash/fragment of the URL.
• scope The token’s scope defines your application’s access to the user’s data. To request multiple scopes, you’ll need to use indexed arrays scope[1]=required-scope. To use Gravatar’s endpoints, you’ll need to require at least one scope:
  • auth You’ll need this scope to work with any of our endpoints. This scope allows the user to authenticate.
  • gravatar-profile:read This scope allows you to access the user’s profile information, like avatar, about info or display name.
  • gravatar-profile:manage This scope allows you to edit the user’s profile information, like avatar, about info or display name.

Example

Before encoding: https://public-api.wordpress.com/oauth2/authorize?client_id=1&redirect_uri=https://your-redirect-url&response_type=token&scope[0]=auth&scope[1]=gravatar-profile:read&scope[2]=gravatar-profile:manage

After encoding: https://public-api.wordpress.com/oauth2/authorize?client_id=1&redirect_uri=https%3A%2F%2Fyour-redirect-url&response_type=token&scope%5B0%5D=auth&scope%5B1%5D=gravatar-profile%3Aread&scope%5B2%5D=gravatar-profile%3Amanage

Receiving an Access Token

After the user approves or denies access to your application, they will be redirected to your redirect_url. If the user has denied access to your app, the redirect will include an access_denied parameter. The flow differs depending on whether you requested a code or token grant.

Server Authentication (Code grant)

The redirect to your application will include a code, which you will need in the next step. The request will look like the following: https://your-redirect-url/?code=cw9hk1xG9k.

This is a time-limited code that your application can exchange for an authorization token. You will need to pass the code to the token endpoint by making a POST request to https://public-api.wordpress.com/oauth2/token.

$curl = curl_init( 'https://public-api.wordpress.com/oauth2/token' );
curl_setopt( $curl, CURLOPT_POST, true );
curl_setopt( $curl, CURLOPT_POSTFIELDS, array(
    'client_id' => your_client_id,
    'redirect_uri' => your_redirect_url,
    'client_secret' => your_client_secret_key,
    'code' => $_GET['code'], // The code from the previous request
    'grant_type' => 'authorization_code'
) );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1);
$auth = curl_exec( $curl );
$secret = json_decode($auth);
$access_key = $secret->access_token;

You are required to pass client_id, client_secret, and redirect_uri for web applications. These parameters have to match the details for your application. Additionally the redirect_uri must match the redirect_uri used during the Authorize step above. grant_type has to be set to authorization_code. code must match the code you received in the redirect. If everything works correctly and the user grants authorization, you will get back a JSON-encoded string containing the token:

{
    "access_token": "YOUR_API_TOKEN",
    "blog_id": "blog ID",
    "blog_url": "blog url",
    "token_type": "bearer"
}

You now have an access token, which should be stored securely. This access token allows your application to act on behalf of the user for Gravatar requests.

CORS error

If you get a CORS error when doing the /oauth2/token request, you are probably using server authentication from the client. This must not be done since this will expose your client_secret to your users.

There are two alternatives to make it work:

• Safer (better): continue using server authentication but make sure your /oauth2/token requests are done from the server.
• Weaker (worse): Use Client Authentication (using response_type=token, see below). In this case the access tokens you obtain will expire in two weeks.

Client Authentication (Token grant)

This is an alternative to Server Authentication but not as safe, so consider using Server Authentication instead.

After the user authenticates, they will be redirected back to your application (same as Server Authentication). But the access token and user information will be included in the URL fragment. So you don’t need to make the /oauth2/token.

Example of redirect URL:

https://your-redirect-url/#access_token=YOUR_API_TOKEN&expires_in=64800&token_type=bearer&site_id=0

This token will allow you to authenticate client-side calls. The token will be valid for two weeks. Use the expires_in fragment to detect when you should prompt for a refresh.

Making an API call

To authenticate a call to our APIs, you need to include your access token with the call. OAuth2 uses a BEARER token that is provided in an Authorization header.

$access_key = 'YOUR_API_TOKEN';
$curl = curl_init( 'https://api.your-redirect-url/v3/me/avatars' );
curl_setopt( $curl, CURLOPT_HTTPHEADER, array( 'Authorization: Bearer ' . $access_key ) );
curl_exec( $curl );

Which will return something like:

[
    {
        "image_id": "image_id",
        "image_url": "https://0.your-redirect-url/userimage/",
        "rating": "G",
        "updated_date": "2024-09-09T18:13:16Z",
        "alt_text": "avatar"
    }
]

This endpoint lists the user’s avatars.

Validating Tokens

It can be helpful to validate the authenticity of a token, specifically that it belongs to your application and the user you are authenticating. This is especially necessary when sending a token over the wire (e.g., a mobile application sending a token as login credentials to an API). To verify a token, use the /oauth/token-info endpoint, passing in the token and your client_id:

https://public-api.wordpress.com/oauth2/token-info?client_id=your_client_id&token=your_token

The endpoint will return an error if the token provided was not authorized for your application. If the token is valid, you will get a JSON-encoded string with the user ID and scope of the token:

{
    "client_id": "your client ID",
    "user_id": "user ID",
    "blog_id": "blog ID",
    "scope": "scope of the token"
}

Testing an application

As the client owner, you can authenticate with the password grant_type, which allows you to skip the authorization step and log in with your username and password. Note that if you are using 2-step authentication (highly recommended), you will need to create an application password to be able to use the password grant_type.

$curl = curl_init( 'https://public-api.wordpress.com/oauth2/token' );
curl_setopt( $curl, CURLOPT_POST, true );
curl_setopt( $curl, CURLOPT_POSTFIELDS, array(
    'client_id' => your_client_id,
    'client_secret' => your_client_secret_key,
    'grant_type' => 'password',
    'username' => your_wpcom_username,
    'password' => your_wpcom_password,
) );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1);
$auth = curl_exec( $curl );
$auth = json_decode($auth);
$access_key = $auth->access_token;

As noted above, this is only available to you as the application owner and not to any other user. This is meant for testing purposes only.

Why WordPress.com?

You might have noticed that our OAuth endpoints are WordPress.com URLs. This is because, under the hood, Gravatar’s profiles are linked to WordPress.com accounts.