GitHub API Tester

Before you paste a live personal access token

GitHub's API evolves — endpoints, media types and permission models change over time. This page is an independent guide, not documentation. Check the official GitHub REST API documentation for authoritative details.

Anatomy of a GitHub API request

GitHub's REST API is one of the better-behaved public APIs, which makes it a good place to learn. Every REST endpoint lives under https://api.github.com, resources are nouns arranged in a predictable hierarchy, and responses are JSON with a consistent shape. The URL prefilled above, https://api.github.com/users/octocat, needs no credentials at all — press Send and you will get a populated JSON user object back immediately. That makes it a useful smoke test when you want to check that a request is reaching GitHub before you introduce authentication as a variable.

Two headers are worth setting deliberately. GitHub documents Accept: application/vnd.github+json as the media type to request, and it supports an explicit X-GitHub-Api-Version header — prefilled above — which pins your request to a dated version of the REST API rather than letting the default drift underneath you. Pinning a version is one of those small disciplines that costs nothing today and saves a confusing afternoon later. If header semantics in general are unfamiliar, the guide to HTTP headers covers the ground.

Authentication is a bearer token: Authorization: Bearer <token>. Select Bearer token in the Auth tab and paste your personal access token, and the header is assembled for you. To confirm exactly what is going over the wire, hit Copy as cURL in the Body tab and read the command it produces.

Valid versus invalid: what each looks like

The cleanest way to test a token is the authenticated-user endpoint, https://api.github.com/user. Unlike /users/octocat, this endpoint has no meaning without a credential — it returns whichever account the token belongs to. A working token produces HTTP 200 and a JSON object with your login, account id and profile fields. That is unambiguous: the token is live, and it belongs to the account you are looking at.

A broken token produces HTTP 401 Unauthorized with a short JSON body whose message reports bad credentials. Note what this does not distinguish: a token that was mistyped, one that expired, and one that was revoked all look the same from outside. If you are confident the token was correct when you copied it, check its expiry date before you go looking for subtler explanations — fine-grained tokens always expire, and expiry is a far more common cause than anything exotic.

There is a third outcome that catches people out: HTTP 200 with a smaller payload than expected. Some endpoints return a reduced representation to unauthenticated or under-permissioned callers rather than failing outright. If a field you were expecting is simply absent rather than null, permissions are a better suspect than a bug.

Creating a token to test with

Personal access tokens are created in your GitHub account's developer settings, where you will be offered both the fine-grained and classic varieties. Choose fine-grained. You will be asked to pick a resource owner, select which repositories the token may touch, and then set individual permissions — contents, issues, pull requests and so on — each to no access, read, or read and write.

Work backwards from the call you actually want to make. If you are reading issues from one repository, grant read access to issues on that one repository and nothing else. The token is displayed exactly once at creation, so copy it then; if you lose it, generate a new one rather than hunting for it. Setting a short expiry for a token you are only using to test is free insurance.

Rate limits and the headers that explain them

GitHub rate-limits by hour, and it tells you exactly where you stand on every single response. Look at the response headers for the x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-used and x-ratelimit-reset family. Remaining is your budget; reset is the epoch timestamp at which it refills. Authenticated requests get a substantially larger allowance than anonymous ones, which is a good practical reason to attach a token even for read-only exploration.

Rather than trusting numbers quoted on a page like this one — which go stale — ask GitHub directly. The https://api.github.com/rate_limit endpoint reports your current limits and remaining quota, and querying it does not itself consume your quota. The "Rate limit" sample button above sends exactly that request.

When you exceed the limit, GitHub responds with 403 or 429 Too Many Requests, depending on which kind of limit you hit. The primary hourly limit and the secondary limits that guard against rapid bursts and expensive operations behave differently, but the correct response is the same: read the Retry-After header if present, otherwise wait until the reset timestamp, and back off rather than retrying in a loop.

The 404 that is really a 403

One GitHub-specific behaviour deserves its own heading, because it sends people down the wrong path more than any other. When your credential lacks access to a private resource, GitHub frequently returns 404 Not Found rather than 403 Forbidden. This is deliberate: a 403 would confirm that the repository exists, which is itself a leak of private information.

So when you are certain a repository exists and the API insists it does not, do not start proofreading the path. Check whether you sent a token at all, whether that token's resource owner includes the repository, and whether the relevant permission was granted. Nine times out of ten the 404 is a permissions problem wearing a disguise.

GitHub also issues short-lived JSON Web Tokens in its app authentication flows. If you are holding one and want to see its claims and expiry without sending it anywhere, the JWT decoder runs entirely in your browser. For inbound GitHub events arriving at an endpoint you host, the webhook tester is the relevant tool, and the general API tester handles anything without GitHub-specific defaults.

Test another provider's API

Frequently asked questions