Keys

As the name suggests, keys are a core part of typeauth. On this page, we'll dive into the different keys endpoints you can use to manage key programmatically. We'll look at how to create, delete, authenticate and list keys.

The key model

The key model contains all the information about your keys, such as their remaining request, any ratelimit applied, environment or metadata. It also contains a reference to the account that holds the key and keys underneath.

Properties

Name
id
Type
string
Description
Unique identifier for the key.
Name
appId
Type
string
Description
The Application ID for the key.
Name
accId
Type
string
Description
The Account ID for the key.
Name
value
Type
string
Description
The value or token for the key.
Name
byteLength
Type
number
Description
Lengtth in bytes for the key or token.
Name
enabled
Type
boolean
Description
Timestamp of when the key was updaated.
Name
environment
Type
string
Description
The environment for the key.
Name
expires
Type
number
Description
expiration time in epoch format for the key
Name
metadata
Type
object
Description
A JSON object to add metadata.
Name
ratelimit
Type
object
Description
A JSON object that specify the rate limit settings for the table.
Name
remaining
Type
number
Description
Number of succesfull request until key is disabled.
Name
refill
Type
object
Description
Number of succesfull request until key is disabled.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the key was updated.
Name
createdAt
Type
timestamp
Description
Timestamp of when the key was created.

Rate Limit Properties

Name
timeWindow
Type
number
Description
Number in seconds of the time interval where the requests are counted.
Name
limit
Type
number
Description
Number of succesfull requests allowed during the interval time.

Metadata Properties

Name
<any>
Type
string
Description
A JSON string key.
Name
<any>
Type
number | string | object
Description
A JSON value for the key.

Refill Properties

Name
interval
Type
string
Description
How often to update the amount succesfullrequests. Posible values are: 'daily', 'hourly', 'weekly' and 'monthly'.
Name
amount
Type
number
Description
Amount of succesfull requests added to the key.

GET/:accountID/keys

List all keys

This endpoint allows you to retrieve a paginated list of all your keys. By default, a maximum of hundred keys are shown per page.

Required attributes

Path parameters

Name
accountID
Type
string
Description
Account ID where the key is created.

Request

GET

/:accountID/keys

curl -G https://api.typeauth.com/:accountID/keys \
  -H "Authorization: Bearer {token}"

Response

{
  "succces": true,
  "message": "",
  "data": [
    {
      "id": "dv2Wr_b4le7V8CLA68IKTEQI8",
      "appId": "H-N2eFoWSFN8CGZhFuYGi",
      "value": "TixDZEhzjxvm4Aq6e5A6nWc35Uyd5gXC",
      "enabled": true
    },
    {
      "id": "h7AgTRXs0DJXtosCKvTGicPFc",
      "appId": "H-N2eFoWSFN8CGZhFuYGi",
      "value": "HdswaOEl10TRDVyBzIuXZCCdWDFh01FM",
      "enabled": true
    },
  ]
}

POST/:accountID/keys/:applicationID/keys

Create an key

This endpoint allows you to add a new key. To add an key , you must provide their name.

Required attributes

Path parameters

Name
accountID
Type
string
Description
Account ID for the key.
Name
applicationID
Type
string
Description
Application ID for the key.

Optional attributes

Name
byteLength
Type
number
Description
Lengtth in bytes for the key or token.
Name
environment
Type
string
Description
The environment for the key.
Name
expires
Type
number
Description
expiration time in epoch format for the key
Name
metadata
Type
object
Description
A JSON object to add metadata.
Name
ratelimit
Type
object
Description
A JSON object that specify the rate limit settings for the table.
Name
remaining
Type
number
Description
Number of succesfull request until key is disabled.
Name
refill
Type
object
Description
Number of succesfull request until key is disabled.

Request

POST

/:accountID/keys/:applicationID/keys

curl https://api.typeauth.com/:accountID/keys/:applicationID/keys \
  -H "Authorization: Bearer {token}" \
  -d '{
    "remaining": 3,
    "ratelimit": {
      "limit": 10,
      "timeWindow": 60
    },
    "environment": "Prod",
    "metadata": {"customerID": "000000000"},
    "bytelength": 33,
    "expires": 10000,
    "refill": {
      "amount": 100
      "interval": "daily"
    },
  }'

Response

{
  "success": true,
  "message": "",
  "data": [
    {
      "id": "23xj2w82jcqPHmvwA7QYuaWR3",
      "appId": "H-N2eFoWSFN8CGZhFuYGi",
      "accId": "KFUEB2_W5SaQ754BUKz4r",
      "value": "kOPOueE4GhBPsHviomSXxoumHfwPgHgd",
      "byteLength": 33,
      "enabled": true,
      "environment": "Prod",
      "expires": 10000,
      "metadata": {"customerID": "000000000"},
      "ratelimit": {
        "limit": 10,
        "timeWindow": 60
      },
      "refill": {
        "amount": 100
        "interval": "daily"
      },
      "remaining": 3,
      "createdAt": "2024-04-14T03:00:30.602Z",
      "updatedAt": "2024-04-14T03:00:30.602Z"
    }
  ]
}

GET/:accountID/keys/:applicationID/keys

Get an key by AppID

This endpoint allows you to retrieve an key by providing their Application id. Refer to the list at the top of this page to see which properties are included with key objects.

Required attributes

Path parameters

Name
accountID
Type
string
Description
Account ID for the key.
Name
applicationID
Type
string
Description
Application ID for the key.

Request

GET

/:accountID/keys/:applicationID/keys

curl https://api.typeauth.com/:accountID/keys/:applicationID/keys \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": [
    {
      "id": "dv2Wr_b4le7V8CLA68IKTEQI8",
      "appId": "H-N2eFoWSFN8CGZhFuYGi",
      "value": "TixDZEhzjxvm4Aq6e5A6nWc35Uyd5gXC",
      "enabled": true
    },
    {
      "id": "h7AgTRXs0DJXtosCKvTGicPFc",
      "appId": "H-N2eFoWSFN8CGZhFuYGi",
      "value": "HdswaOEl10TRDVyBzIuXZCCdWDFh01FM",
      "enabled": true
    },
  ]
}

GET/:accountID/keys/:applicationID/keys/:keyID

Get a key by Key ID

This endpoint allows you to retrieve an key by providing their Application id. Refer to the list at the top of this page to see which properties are included with key objects.

Required attributes

Path parameters

Name
accountID
Type
string
Description
Account ID for the key.
Name
applicationID
Type
string
Description
Application ID for the key.
Name
keyID
Type
string
Description
Key ID for the key.

Request

GET

/:accountID/keys/:applicationID/keys/:keyID

curl https://api.typeauth.com/:accountID/keys/:applicationID/keys/:keyID \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "",
  "data": [
    {
      "id": "23xj2w82jcqPHmvwA7QYuaWR3",
      "appId": "H-N2eFoWSFN8CGZhFuYGi",
      "accId": "KFUEB2_W5SaQ754BUKz4r",
      "value": "kOPOueE4GhBPsHviomSXxoumHfwPgHgd",
      "byteLength": 33,
      "enabled": true,
      "environment": "Prod",
      "expires": 10000,
      "metadata": {"customerID": "000000000"},
      "ratelimit": {
        "limit": 10,
        "timeWindow": 60
      },
      "refill": {
        "amount": 100
        "interval": "daily"
      }
      "remaining": 3,
      "createdAt": "2024-04-14T03:00:30.602Z",
      "updatedAt": "2024-04-14T03:00:30.602Z"
    }
  ]
}

POST/authenticate

Authenticate key

This endpoint allows you to perform an update on an key.

Optional attributes

Name
name
Type
string
Description
The username for the key.
Name
prefix
Type
string
Description
The phone number for the key.
Name
description
Type
string
Description
The avatar image URL for the contact.

Request

PUT

/authenticate

curl -X PUT https://api.typeauth.com/authenticate \
  -H "Authorization: Bearer {token}" \
  -d '{
    "key": "00000111112222333444455666",
  }'

Response

{
  "success": true,
  "message": "",
  "data": [
    {
      "valid": true,
      "rate_limit": {
        "limit": 10,
        "timeWindow": 60,
        "remaining": 9
      },
      "remaining": {
        "remaining": 2
      },
      "enabled": true
    }
  ]
}

DELETE/:accountID/keys/:applicationID/keys/:keyID/delete

Delete a key

This endpoint allows you to delete an key. Note: This will also delete the keys associated to the given key.

Required attributes

Path parameters

Name
accountID
Type
string
Description
Account ID for the key.
Name
applicationID
Type
string
Description
Application ID for the key.
Name
keyID
Type
string
Description
Key ID for the key.

Request

DELETE

/:accountID/keys/:applicationID/keys/:keyID/delete

curl -X DELETE https://api.typeauth.com/:accountID/keys/:applicationID/keys/:keyID/delete \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Key deleted succesfully.",
  "data": [ ]
}