Client library for TheAuthAPI
Contents- Client library for TheAuthAPI
Installation
This library is published on npm, you can add it as a dependency using the following commandConfiguration
You’ll need to configure the library with youraccess key
and account id
, you can grab these from TheAuthAPI dashboard.
For further instructions on creating an account, check out our how to guides.
Imports
CommonJS
ES Modules
Usage
After initiating the client, you can access endpoint methods using the following pattern:[object instance].[endpoint].[method]
For example, getting the projects for an account would be: theAuthApiClient.projects.getProjects("ACCOUNT_ID")
,
Similarly, getting the api keys would be:
theAuthApiClient.apiKeys.getKeys("PROJECT_ID")
endpoint | attribute | example |
---|---|---|
/api-keys | apiKeys | client.apiKeys.createKey("MY_KEY") |
/projects | projects | client.projects.createProject("MY_PROJECT") |
/accounts | accounts | client.accounts.createAccount("MY_ACCOUNT") |
HTTP Method | method name | example |
---|---|---|
POST | create* | client.apiKeys.createKey({ name: "KEY_NAME", projectId: "PROJECT_ID" }) |
GET | get* | client.apiKeys.getKeys() |
DELETE | delete* | client.apiKeys.deleteKey("MY_KEY") |
PATCH | update* | client.apiKeys.updateKey("MY_KEY", { name: "UPDATED_KEY_NAME" }) |
Example: Validating an API-Key
You can easily validate an API key usingapiKeys.isValidKey
which returns true
if the key is valid, false
otherwise.
isValidKey
throws an ApiRequestError
if there’s a network issue, it’s advised to wrap it in a try/catch
to handle the potential error
apiKeys.authenticateKey
which returns an ApiKey.
Example: Listing API-keys
getKeys
projectId
where the keys are not active
projectId
when listing the API keys:
getKeys({ projectId: "PROJECT_ID" })
, otherwise if your access key is created at project level, you don’t have to specify projectId
,
the access key’s projectId
will be used to get the API-keys (i.e. you’ll see only the keys of the project your access key is created against)
Example: Listing the projects of an account
Example: Listing projects and associated API-Keys
Example: Creating an API-Key
Example: Rotating an API-Key
When you need to quickly and securely rotate a compromised key, while preserving the key’s metadata, use therotateKey
method. This method while clone your key and return you with a new one.
Handling Errors
ApiRequestError
Thrown when there’s a network or a connectivity issue, for example, if the client didn’t establish any network connection with the hostApiResponseError
Thrown when the server responds with an HTTP status code not in the2xx
range. ApiRequestError
provides two properties to distinguish the type of the error
statusCode
HTTP status codemessage
the message the server responded with in the body
Example: Getting a key throws an ApiResponseError if the key is invalid
If you try to GET an invalid key usingapiKeys.getKey("invalid-key")
, the server responds with a 404 error and an ApiResponseError
is thrown
statusCode
, “Invalid client Key” is the message
, you can access these properties using error.statusCode
and error.message
respectively
Error
Unknown error, just a normal javascript errorHandling Errors the Right Way
Since all the possible thrown errors are instances of classes, we can check the type of the thrown error and handle it accordinglyTypescript
This library is written in Typescript, types are provided out of the box. Example of usage with Typescript:📙 Further Reading
- Create your account https://theauthapi.com
- View our Knowledge Base help centre
- Read our API docs
- Articles on best Auth practice - https://theauthapi.com/articles
- Meet the team behind The Auth API - That API Company