GitHub API Token Validation for Node.js
validate-github-token is a npm package to validate GitHub API OAuth token.
This package can validate the given token
- is actually authorized by API endpoint
- has expected API scopes
- doesn't have unexpected API scopes
and returns the following information as the result of validation:
- API scopes which the given token has
- Rate limit
See GitHub official authentication document for more details.
This package aims to make a human-friendly error before actually calling GitHub APIs. It is useful
for validating inputs of GitHub Action if you're making a JavaScript Action.
Installation
npm install --save validate-github-token
JavaScript Example
const { validateGitHubToken, ValidationError } = require('validate-github-token');
(async () => {
try {
const validated = await validateGitHubToken(
'your-secret-api-token',
{
scope: {
included: ['public_repo']
}
}
);
console.log('Token scopes:', validated.scopes);
console.log('API rate limit remaining:', validated.rateLimit.remaining);
} catch(err) {
if (err instanceof ValidationError) {
console.error(`Validation failed!: ${err.message}`);
} else {
throw err;
}
}
})();
API
import { validateGitHubToken, ValidationError } from 'validate-github-token';
import { ValidateOptions, RateLimit, Validated } from 'validate-github-token';
interface ValidateOptions
A TypeScript interface for configuring the validation behavior. It's keys are as follows:
userName: string
: GitHub user name like "rhysd"
for @rhysd. If this value is set, the endpoint will
check the token against the user Optionalscope: Object
: Scope validation behavior Optional
included: Array<string>
: Scope names which should be added to the token Optionalexcluded: Array<string>
: Scope names which should NOT be added to the token Optionalexact: Array<string>
: Scope names should exactly match to scopes of the token Optional
agent: https.Agent
: Node.js HTTPS agent. For example please pass https-proxy-agent for proxy support OptionalendpointUrl: string
: Custom API endpoint URL. Default value is "https://api.github.com"
Optional
e.g.
import {ValidateOptions} from 'validate-github-token';
const opts: ValidateOptions = {
scope: {
included: ['public_repo'],
excluded: ['user'],
},
endpointUrl: 'https://github.your.company.com/api/v3',
};
async function validateGitHubToken(token, options?)
A function which validates the given token for the given user. Validation behavior can be configured
with the 3rd parameter. It returns the information given from API endpoint.
Validation failure is thrown as ValidationError
.
Parameters
token: string
: API token to be validated Requiredoptions: Object
: Objects to configure validation behavior Optional
Return value
Returns a promise which is resolved to Validated
interface object. Please read following 'interface Validated'
section for more details.
Exceptions
ValidationError
: Thrown when the given token is actually not authorized or its scopes don't meet options.scope
option valueError
: Thrown when unexpected errors such as network error happen
interface Validated
A TypeScript interface contains the all information returned from API endpoint.
scopes: Array<string>
: An array of scope names added to the API tokenrateLimit: RateLimit
: Rate limit information
interface RateLimit
A TypeScript interface contains the rate limit information returned from an API endpoint.
Please read GitHub's official rate limit documentation for more details.
limit: number
: Max rate limit countremaining: number
: Remaining rate limit countreset: Date
: The date when the rate limit count is reset
License
Distributed under the MIT license.