aniSearch OAuth 2.0 Authorization Guide v2025-05-01

← Back to API Access at aniSearch

This document describes how third-party applications can obtain and refresh OAuth 2.0 tokens to access the aniSearch API on behalf of a user. It covers the endpoints, typical token lifetimes, and example requests without delving into internal implementation details.

For questions regarding the API or this documentation, please contact api@anisearch.com.

Table of Contents

• Base Domains
• Overview
• Client Registration
• Available Scopes
• Obtaining Access Tokens (Authorization Code Flow)
  • Step 1: Generate Code Verifier and Challenge (PKCE)
  • Step 2: Request Authorization
  • Step 3: User Authentication & Authorization
  • Step 4: Receive Authorization Code
  • Step 5: Exchange Authorization Code for Tokens
• Refreshing Access Tokens
• Revoking Tokens
• Common Error Codes
• Calling the API
  • User API
  • Ratings API

Base Domains

The aniSearch website and OAuth endpoints are available under different domains corresponding to different languages. The API itself is accessed via api.anisearch.com.

Use the base domain that matches the user’s language preference when constructing OAuth endpoint URLs.

Overview

The aniSearch API uses the OAuth 2.0 protocol for authentication and authorization.

Currently supported grant type:

• Authorization Code Grant with Proof Key for Code Exchange (PKCE).

OAuth Endpoints

Token Details

Client Registration

Before you can start the authorization process, you need to register your application with aniSearch. Registered users can manage their OAuth applications via the Apps tab within their user control panel.

During registration, you will need to provide an application name and a Redirect URI where users will be sent back after authorization. Currently, only one Redirect URI can be registered per application.

Upon successful registration, you will receive a unique client_id and client_secret. Ensure you store these client credentials securely.

Available Scopes

Scopes define the level of access your application requests from the user. Request only the scopes necessary for your application’s functionality.

Obtaining Access Tokens (Authorization Code Flow)

This flow allows users to grant your application access to their aniSearch data without sharing their credentials.

Step 1: Generate Code Verifier and Challenge (PKCE)

To implement the PKCE requirement, your application must first generate a cryptographically random code_verifier and the corresponding code_challenge.

<?php
// Generate a high-entropy random string for the code verifier (min 43, max 128 chars)
$codeVerifier = bin2hex(random_bytes(32)); // Creates a 64-character hex string

// Store $codeVerifier in the user’s session or similar temporary storage for Step 5
$_SESSION['code_verifier'] = $codeVerifier;

// Generate the S256 code challenge required by the server
// This process:
// 1. Creates a binary SHA-256 hash of the code verifier (hash function with 'true' parameter)
// 2. Base64-encodes this binary hash
// 3. Replaces URL-unsafe characters and removes padding to make it URL-safe
$codeChallenge = rtrim(strtr(base64_encode(hash('sha256', $codeVerifier, true)), '+/', '-_'), '=');

Step 2: Request Authorization

Redirect the user’s browser to the aniSearch authorization endpoint (e.g., {BASE_DOMAIN}/oauth/authorize) with the following query parameters:

GET {BASE_DOMAIN}/oauth/authorize?
    response_type=code
    &client_id=YOUR_CLIENT_ID
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
    &scope=DESIRED_SCOPES
    &state=CSRF_PROTECTION_STATE
    &code_challenge=YOUR_GENERATED_CODE_CHALLENGE
    &code_challenge_method=S256

Step 3: User Authentication & Authorization

aniSearch will prompt the user to log in (if they aren’t already). The user will then be presented with a consent screen asking them to authorize the requested scope(s) for your application. The user can approve or deny the request.

Step 4: Receive Authorization Code

If the user approves, aniSearch redirects the browser back to your specified redirect_uri with an authorization_code and the state parameter you initially provided:

HTTP/1.1 302 Found
Location: YOUR_REGISTERED_REDIRECT_URI?code=AUTHORIZATION_CODE&state=CSRF_PROTECTION_STATE

Your application must:

1. Verify that the received state parameter exactly matches the one generated and stored before Step 2.
2. Extract the authorization_code. This code is short-lived (valid for 10 minutes) and can only be used once.

Step 5: Exchange Authorization Code for Tokens

Your application’s backend server makes a POST request to the aniSearch token endpoint (e.g., {BASE_DOMAIN}/oauth/token) to exchange the authorization_code for an access token and a refresh token.

Client authentication is required. You can either use HTTP Basic Authentication (preferred: `Authorization: Basic BASE64(client_id:client_secret)`) or include the client_id and client_secret in the request body.

Request (using request body parameters for client auth):

POST {BASE_DOMAIN}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE_FROM_STEP_4
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code_verifier=YOUR_CODE_VERIFIER_FROM_STEP_1

Successful Response (HTTP 200 OK):

aniSearch validates the request (including the code_verifier against the code_challenge associated with the code) and returns a JSON response containing the tokens:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "ACCESS_TOKEN_STRING",
  "refresh_token": "REFRESH_TOKEN_STRING"
}

The response includes the following fields:

Store the access_token and refresh_token securely, associated with the user.

Refreshing Access Tokens

When an access token expires (after 1 hour), use the corresponding refresh token to obtain a new access token without requiring user interaction, as long as the refresh token is still valid (within 30 days) and hasn’t been revoked.

Make a POST request to the token endpoint (e.g., {BASE_DOMAIN}/oauth/token). Client authentication (Basic Auth or request body parameters) is required, just like in Step 5.

POST {BASE_DOMAIN}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=USER_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

The response format upon success (HTTP 200 OK) is the same as in Step 5 of the authorization flow, providing a new access token and potentially a new refresh token. Always store the latest refresh token received, as older ones might be invalidated.

If the refresh token is invalid or expired, the server will return an error (e.g., `invalid_grant`), and you must prompt the user to re-authorize your application via the full Authorization Code flow (starting from Step 2).

Revoking Tokens

To invalidate a refresh token or an access token (e.g., when a user logs out of your application or explicitly disconnects it), make a POST request to the revocation endpoint (e.g., {BASE_DOMAIN}/oauth/revoke).

Client authentication via HTTP Basic Authentication is required for this endpoint.

POST {BASE_DOMAIN}/oauth/revoke
Authorization: Basic BASE64_ENCODED(YOUR_CLIENT_ID:YOUR_CLIENT_SECRET)
Content-Type: application/x-www-form-urlencoded

token=TOKEN_TO_REVOKE
&token_type_hint=HINT

A successful revocation always returns an HTTP 200 OK status code with an empty body, regardless of whether the token was found and revoked or was already invalid. Your application should remove the revoked token(s) from its storage.

Common Error Codes

When requests to the OAuth endpoints fail, the server returns an error response in JSON format as defined in the OAuth 2.0 specification. Understanding these errors can help you troubleshoot issues and implement appropriate handling in your client.

Error responses are returned with an appropriate HTTP status code (typically 400 for client errors, 401 for authentication failures, and 500 for server errors) and include a JSON body with the following structure:

{
  "error": "error_code",
  "error_description": "Human-readable explanation"
}

Always handle these errors gracefully in your application, showing appropriate messages to users and implementing retry logic where appropriate.

Calling the API

Once you have a valid access token, you can make requests to the aniSearch API endpoints hosted at https://api.anisearch.com/v1/.

Include the access token in the Authorization HTTP header using the Bearer scheme:

Authorization: Bearer YOUR_ACCESS_TOKEN

The specific API resources you can access depend on the scopes granted by the user:

If an API request fails with an authentication error (e.g., HTTP 401 Unauthorized), it likely means the access token has expired or been revoked. You should attempt to refresh the token using the refresh token (see Refreshing Access Tokens). If refreshing succeeds, retry the original API request once with the new access token. If refreshing fails, the user needs to re-authorize.