OAuth

Before we get into the specifics of OAuth authorization in Gravatar, please check our other available APIs: profiles and avatars. They allow for a more simple integration and might be enough depending on your use case.

Psst! Looking for the available endpoints (OpenAPI definition)? Jump to API Endpoints section below.

Overview

Some of our REST endpoints need OAuth2 authorization. This documentation will help you understand how to obtain the necessary tokens for your requests.

All steps are described below, but in a nutshell, you’ll need to follow these steps:

Create or Update your Application
Make your client redirect users to the authorization endpoint https://public-api.wordpress.com/oauth2/authorize
Receive your access token in your redirect URL:
1. If you requested a code grant (intended for servers):
  1. The redirect to your application will include a code in the query: https://your-redirect-url/?code=cw9hk1xG9k
  2. Make a POST request to https://public-api.wordpress.com/oauth2/token with the code you obtained
  3. The response will include the access token in the JSON-encoded response
2. If you requested a token grant (intended for clients):
  1. The redirect to your application will include an access token in the fragment: https://your-redirect-url/#access_token=cw9hk1xG9k
Use the access token in your request in the Authorization header: Authorization: Bearer TOKEN

If you are still getting familiar with OAuth 2, this might all sound confusing. But don’t worry! It’s way easier than it sounds.

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.

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.

API Endpoints

The best way to explore our endpoints (and play around with them) is to check Gravatar’s Developer Console.

The Developer Console uses our OpenAPI spec (https://api.gravatar.com/v3/openapi) which is our most up-to-date source of truth.

At the moment, the console requires you to be logged in into Gravatar.com. This will eventually change, but until then please signup/login to use it.

Below you can find a list of the current operations (best effort to keep it up to date).

Avatars Operations

GET /me/avatars

Description: Retrieves a list of available avatars for the authenticated user.

Query Parameters:

selected_email_hash (string, optional)

Output: Array of Avatar

POST /me/avatars

Description: Uploads a new avatar image for the authenticated user.

Query Parameters:

selected_email_hash (string, optional)
select_avatar ([‘boolean’, ‘null’], optional)

Input Body:

data (binary, required) – multipart/form-data

Output: Avatar

DELETE /me/avatars/{imageHash}

Description: Deletes a specific avatar for the authenticated user.

Path Parameters:

imageHash (string, required)

Output: No content

PATCH /me/avatars/{imageHash}

Description: Updates the avatar data for a given avatar for the authenticated user.

Path Parameters:

imageHash (string, required)

Input Body:

rating (any, optional)
alt_text (string, optional)

Output: Avatar

POST /me/avatars/{imageId}/email

Description: Sets the avatar for the provided email hash.

Path Parameters:

imageId (string, required)

Input Body:

email_hash (string, required)

Output: No content

Profiles Operations

GET /me/profile

Description: Returns the information available for the authenticated user. It’s equivalent to the full profile information available in the /profiles/{profileIdentifier} endpoint.

Output: Profile

PATCH /me/profile

Description: Updates the profile information for the authenticated user. Only a subset of Profile fields are available for update. Partial updates are supported, so only the provided fields will be updated. To unset a field, set it explicitly to an empty string.

Input Body:

display_name (string, optional)
description (string, optional)
pronunciation (string, optional)
pronouns (string, optional)
location (string, optional)
job_title (string, optional)
company (string, optional)

Output: Profile

GET /me/associated-email

Description: Checks if the provided email address is associated with the authenticated user.

Query Parameters:

email_hash (string, required)

Output: AssociatedResponse

Schema Definitions

AssociatedResponse

Properties:

associated (boolean, required) – Whether the entity is associated with the account. (e.g. True)

Avatar

An avatar that the user has already uploaded to their Gravatar account.

Properties:

image_id (string, required) – Unique identifier for the image. (e.g. 38be15a98a2bbc40df69172a2a8349)
image_url (string, required) – Image URL (e.g. https://gravatar.com/userimage/252014526/d38bele5a98a2bbc40df69172a2a8348.jpeg)
rating (string, required) – Rating associated with the image.
alt_text (string, required) – Alternative text description of the image. (e.g. Gravatar's avatar image. Gravatar is a service for providing globally unique avatars.)
selected (boolean, optional) – Whether the image is currently selected as the provided selected email’s avatar. (e.g. True)
updated_date (string, required) – Date and time when the image was last updated. (e.g. 2021-10-01T12:00:00Z)

CryptoWalletAddress

A crypto currency wallet address the user accepts.

Properties:

label (string, required) – The label for the crypto currency. (e.g. ETH)
address (string, required) – The wallet address for the crypto currency. (e.g. 0xABC123...)

Error

An error response from the API.

Properties:

error (string, required) – The error message
code (string, optional) – The error code for the error message

GalleryImage

A gallery image a user has uploaded.

Properties:

url (string, required) – The URL to the image. (e.g. https://0.gravatar.com/userimage/5/04bbd674f72c703f6335e2e7a00acc9a)
alt_text (string, optional) – The image alt text. (e.g. A beautiful sunset)

Interest

An interest the user has added to their profile.

Properties:

id (integer, required) – The unique identifier for the interest. (e.g. 1)
name (string, required) – The name of the interest. (e.g. photography)

Language

The languages the user knows. This is only provided in authenticated API requests.

Properties:

code (string, required) – The language code. (e.g. en)
name (string, required) – The language name. (e.g. English)
is_primary (boolean, required) – Whether the language is the user’s primary language. (e.g. True)
order (integer, required) – The order of the language in the user’s profile. (e.g. 1)

Link

A link the user has added to their profile.

Properties:

label (string, required) – The label for the link. (e.g. Personal Website)
url (string, required) – The URL to the link. (e.g. https://example.com)

Profile

A user’s profile information.

Properties:

hash (string, required) – The SHA256 hash of the user’s primary email address. (e.g. 31c5543c1734d25c7206f5fd591525d0295bec6fe84ff82f946a34fe970a1e66)
display_name (string, required) – The user’s display name. This is the name that is displayed on their profile. (e.g. Alex Morgan)
profile_url (string, required) – The full URL for the user’s profile. (e.g. https://gravatar.com/example)
avatar_url (string, required) – The URL for the user’s avatar image if it has been set. (e.g. https://0.gravatar.com/avatar/33252cd1f33526af53580fcb1736172f06e6716f32afdd1be19ec3096d15dea5)
avatar_alt_text (string, required) – The alt text for the user’s avatar image if it has been set. (e.g. Alex Morgan's avatar image. Alex is smiling and standing in beside a large dog who is looking up at Alex.)
location (string, required) – The user’s location. (e.g. New York, USA)
description (string, required) – The about section on a user’s profile. (e.g. I like playing hide and seek.)
job_title (string, required) – The user’s job title. (e.g. Landscape Architect)
company (string, required) – The user’s current company’s name. (e.g. ACME Corp)
verified_accounts (array of VerifiedAccount, required) – A list of verified accounts the user has added to their profile. This is limited to a max of 4 in unauthenticated requests.
pronunciation (string, required) – The phonetic pronunciation of the user’s name. (e.g. Al-ex Mor-gan)
pronouns (string, required) – The pronouns the user uses. (e.g. She/They)
timezone (string, optional) – The timezone the user has. This is only provided in authenticated API requests. (e.g. Europe/Bratislava)
languages (array of Language, optional) – The languages the user knows. This is only provided in authenticated API requests.
first_name (string, optional) – User’s first name. This is only provided in authenticated API requests. (e.g. Alex)
last_name (string, optional) – User’s last name. This is only provided in authenticated API requests. (e.g. Morgan)
is_organization (boolean, optional) – Whether user is an organization. This is only provided in authenticated API requests. (e.g. False)
header_image (string, optional) – The header image used in the main profile card. (e.g. url('https://gravatar.com/userimage/209234789/cdebd0ed415kfa2g562ba5c34b1570c2') no-repeat 50% 1% / 100%)
hide_default_header_image: Whether to hide the default header image. (e.g. False)
background_color (string, optional) – The profile background color. (e.g. rgb(33, 0, 166))
links (array of Link, optional) – A list of links the user has added to their profile. This is only provided in authenticated API requests.
interests (array of Interest, optional) – A list of interests the user has added to their profile. This is only provided in authenticated API requests.
payments (object, optional) – The user’s public payment information. This is only provided in authenticated API requests.
contact_info (object, optional) – The user’s contact information. This is only available if the user has chosen to make it public. This is only provided in authenticated API requests.
gallery (array of GalleryImage, optional) – Additional images a user has uploaded. This is only provided in authenticated API requests.
number_verified_accounts (integer, optional) – The number of verified accounts the user has added to their profile. This count includes verified accounts the user is hiding from their profile. This is only provided in authenticated API requests. (e.g. 3)
last_profile_edit ([‘string’, ‘null’], optional) – The date and time (UTC) the user last edited their profile. This is only provided in authenticated API requests. (e.g. 2021-10-01T12:00:00Z)
registration_date ([‘string’, ‘null’], optional) – The date the user registered their account. This is only provided in authenticated API requests. (e.g. 2021-10-01T12:00:00Z)

Rating

Rating associated with the image.

Possible values:

G
PG
R
X

VerifiedAccount

A verified account on a user’s profile.

Properties:

is_hidden (boolean, required) – Whether the verified account is hidden from the user’s profile. (e.g. False)

service_type (string, required) – The type of the service. (e.g. tumblr)

service_label (string, required) – The name of the service. (e.g. Tumblr)

service_icon (string, required) – The URL to the service’s icon. (e.g. https://gravatar.com/icons/tumblr-alt.svg)

url (string, required) – The URL to the user’s profile on the service. (e.g. https://example.tumblr.com/)