@unkey/api 0.17.0 → 0.19.0

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { PermissionQuery } from '@unkey/rbac';
+export { Flatten, and, or } from '@unkey/rbac';
+
 /**
  * This file was auto-generated by openapi-typescript.
  * Do not make direct changes to the file.
@@ -249,7 +252,7 @@ interface paths {
               [key: string]: unknown;
             };
             /**
-             * @description A list of roles that this key should have. New roles will be created if they don't exist yet.
+             * @description A list of roles that this key should have. If the role does not exist, an error is thrown
              * @example [
              *   "admin",
              *   "finance"
@@ -311,6 +314,17 @@ interface paths {
              * @example false
              */
             enabled?: boolean;
+            /**
+             * @description Environments allow you to divide your keyspace.
+             *
+             * Some applications like Stripe, Clerk, WorkOS and others have a concept of "live" and "test" keys to
+             * give the developer a way to develop their own application without the risk of modifying real world
+             * resources.
+             *
+             * When you set an environment, we will return it back to you when validating the key, so you can
+             * handle it correctly.
+             */
+            environment?: string;
           };
         };
       };
@@ -670,7 +684,7 @@ interface paths {
         };
       };
       responses: {
-        /** @description The configuration for a single key */
+        /** @description Usage numbers over time */
         200: {
           content: {
             "application/json": {
@@ -1026,232 +1040,6 @@ interface paths {
       };
     };
   };
-  "/v1/keys/{keyId}": {
-    put: {
-      parameters: {
-        path: {
-          keyId: string;
-        };
-      };
-      requestBody: {
-        content: {
-          "application/json": {
-            /**
-             * @description The name of the key
-             * @example Customer X
-             */
-            name?: string | null;
-            /**
-             * @description The id of the tenant associated with this key. Use whatever reference you have in your system to identify the tenant. When verifying the key, we will send this field back to you, so you know who is accessing your API.
-             * @example user_123
-             */
-            ownerId?: string | null;
-            /**
-             * @description Any additional metadata you want to store with the key
-             * @example {
-             *   "roles": [
-             *     "admin",
-             *     "user"
-             *   ],
-             *   "stripeCustomerId": "cus_1234"
-             * }
-             */
-            meta?: {
-              [key: string]: unknown;
-            } | null;
-            /**
-             * @description The unix timestamp in milliseconds when the key will expire. If this field is null or undefined, the key is not expiring.
-             * @example 0
-             */
-            expires?: number | null;
-            /**
-             * @description Unkey comes with per-key ratelimiting out of the box. Set `null` to disable.
-             * @example {
-             *   "type": "fast",
-             *   "limit": 10,
-             *   "refillRate": 1,
-             *   "refillInterval": 60
-             * }
-             */
-            ratelimit?: ({
-              /**
-               * @description Fast ratelimiting doesn't add latency, while consistent ratelimiting is more accurate.
-               * @enum {string}
-               */
-              type: "fast" | "consistent";
-              /** @description The total amount of burstable requests. */
-              limit: number;
-              /** @description How many tokens to refill during each refillInterval. */
-              refillRate: number;
-              /** @description Determines the speed at which tokens are refilled, in milliseconds. */
-              refillInterval: number;
-            }) | null;
-            /**
-             * @description The number of requests that can be made with this key before it becomes invalid. Set `null` to disable.
-             * @example 1000
-             */
-            remaining?: number | null;
-          };
-        };
-      };
-      responses: {
-        /** @description The key was successfully updated, it may take up to 30s for this to take effect in all regions */
-        200: {
-          content: {
-            "application/json": Record<string, never>;
-          };
-        };
-        /** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
-        400: {
-          content: {
-            "application/json": components["schemas"]["ErrBadRequest"];
-          };
-        };
-        /** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
-        401: {
-          content: {
-            "application/json": components["schemas"]["ErrUnauthorized"];
-          };
-        };
-        /** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
-        403: {
-          content: {
-            "application/json": components["schemas"]["ErrForbidden"];
-          };
-        };
-        /** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
-        404: {
-          content: {
-            "application/json": components["schemas"]["ErrNotFound"];
-          };
-        };
-        /** @description This response is sent when a request conflicts with the current state of the server. */
-        409: {
-          content: {
-            "application/json": components["schemas"]["ErrConflict"];
-          };
-        };
-        /** @description The user has sent too many requests in a given amount of time ("rate limiting") */
-        429: {
-          content: {
-            "application/json": components["schemas"]["ErrTooManyRequests"];
-          };
-        };
-        /** @description The server has encountered a situation it does not know how to handle. */
-        500: {
-          content: {
-            "application/json": components["schemas"]["ErrInternalServerError"];
-          };
-        };
-      };
-    };
-  };
-  "/v1/keys/:keyId": {
-    get: {
-      responses: {
-        /** @description The configuration for a single key */
-        200: {
-          content: {
-            "application/json": components["schemas"]["Key"];
-          };
-        };
-        /** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
-        400: {
-          content: {
-            "application/json": components["schemas"]["ErrBadRequest"];
-          };
-        };
-        /** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
-        401: {
-          content: {
-            "application/json": components["schemas"]["ErrUnauthorized"];
-          };
-        };
-        /** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
-        403: {
-          content: {
-            "application/json": components["schemas"]["ErrForbidden"];
-          };
-        };
-        /** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
-        404: {
-          content: {
-            "application/json": components["schemas"]["ErrNotFound"];
-          };
-        };
-        /** @description This response is sent when a request conflicts with the current state of the server. */
-        409: {
-          content: {
-            "application/json": components["schemas"]["ErrConflict"];
-          };
-        };
-        /** @description The user has sent too many requests in a given amount of time ("rate limiting") */
-        429: {
-          content: {
-            "application/json": components["schemas"]["ErrTooManyRequests"];
-          };
-        };
-        /** @description The server has encountered a situation it does not know how to handle. */
-        500: {
-          content: {
-            "application/json": components["schemas"]["ErrInternalServerError"];
-          };
-        };
-      };
-    };
-    delete: {
-      responses: {
-        /** @description The key was successfully revoked, it may take up to 30s for this to take effect in all regions */
-        200: {
-          content: {
-            "application/json": Record<string, never>;
-          };
-        };
-        /** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
-        400: {
-          content: {
-            "application/json": components["schemas"]["ErrBadRequest"];
-          };
-        };
-        /** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
-        401: {
-          content: {
-            "application/json": components["schemas"]["ErrUnauthorized"];
-          };
-        };
-        /** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
-        403: {
-          content: {
-            "application/json": components["schemas"]["ErrForbidden"];
-          };
-        };
-        /** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
-        404: {
-          content: {
-            "application/json": components["schemas"]["ErrNotFound"];
-          };
-        };
-        /** @description This response is sent when a request conflicts with the current state of the server. */
-        409: {
-          content: {
-            "application/json": components["schemas"]["ErrConflict"];
-          };
-        };
-        /** @description The user has sent too many requests in a given amount of time ("rate limiting") */
-        429: {
-          content: {
-            "application/json": components["schemas"]["ErrTooManyRequests"];
-          };
-        };
-        /** @description The server has encountered a situation it does not know how to handle. */
-        500: {
-          content: {
-            "application/json": components["schemas"]["ErrInternalServerError"];
-          };
-        };
-      };
-    };
-  };
   "/v1/keys": {
     post: {
       requestBody: {
@@ -1505,282 +1293,12 @@ interface paths {
                * - FORBIDDEN: the key is not allowed to access the api
                * - USAGE_EXCEEDED: the key has exceeded its request limit
                * - RATE_LIMITED: the key has been ratelimited,
+               * - INSUFFICIENT_PERMISSIONS: you do not have the required permissions to perform this action
                *
                * @example NOT_FOUND
                * @enum {string}
                */
-              code?: "NOT_FOUND" | "FORBIDDEN" | "USAGE_EXCEEDED" | "RATE_LIMITED" | "UNAUTHORIZED" | "DISABLED";
-            };
-          };
-        };
-        /** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
-        400: {
-          content: {
-            "application/json": components["schemas"]["ErrBadRequest"];
-          };
-        };
-        /** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
-        401: {
-          content: {
-            "application/json": components["schemas"]["ErrUnauthorized"];
-          };
-        };
-        /** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
-        403: {
-          content: {
-            "application/json": components["schemas"]["ErrForbidden"];
-          };
-        };
-        /** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
-        404: {
-          content: {
-            "application/json": components["schemas"]["ErrNotFound"];
-          };
-        };
-        /** @description This response is sent when a request conflicts with the current state of the server. */
-        409: {
-          content: {
-            "application/json": components["schemas"]["ErrConflict"];
-          };
-        };
-        /** @description The user has sent too many requests in a given amount of time ("rate limiting") */
-        429: {
-          content: {
-            "application/json": components["schemas"]["ErrTooManyRequests"];
-          };
-        };
-        /** @description The server has encountered a situation it does not know how to handle. */
-        500: {
-          content: {
-            "application/json": components["schemas"]["ErrInternalServerError"];
-          };
-        };
-      };
-    };
-  };
-  "/v1/apis": {
-    post: {
-      requestBody: {
-        content: {
-          "application/json": {
-            /**
-             * @description The name for your API. This is not customer facing.
-             * @example my-api
-             */
-            name: string;
-          };
-        };
-      };
-      responses: {
-        /** @description The configuration for an api */
-        200: {
-          content: {
-            "application/json": {
-              /**
-               * @description The id of the api
-               * @example api_134
-               */
-              apiId: string;
-            };
-          };
-        };
-        /** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
-        400: {
-          content: {
-            "application/json": components["schemas"]["ErrBadRequest"];
-          };
-        };
-        /** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
-        401: {
-          content: {
-            "application/json": components["schemas"]["ErrUnauthorized"];
-          };
-        };
-        /** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
-        403: {
-          content: {
-            "application/json": components["schemas"]["ErrForbidden"];
-          };
-        };
-        /** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
-        404: {
-          content: {
-            "application/json": components["schemas"]["ErrNotFound"];
-          };
-        };
-        /** @description This response is sent when a request conflicts with the current state of the server. */
-        409: {
-          content: {
-            "application/json": components["schemas"]["ErrConflict"];
-          };
-        };
-        /** @description The user has sent too many requests in a given amount of time ("rate limiting") */
-        429: {
-          content: {
-            "application/json": components["schemas"]["ErrTooManyRequests"];
-          };
-        };
-        /** @description The server has encountered a situation it does not know how to handle. */
-        500: {
-          content: {
-            "application/json": components["schemas"]["ErrInternalServerError"];
-          };
-        };
-      };
-    };
-  };
-  "/v1/apis/{apiId}": {
-    get: {
-      parameters: {
-        path: {
-          apiId: string;
-        };
-      };
-      responses: {
-        /** @description The configuration for an api */
-        200: {
-          content: {
-            "application/json": {
-              /**
-               * @description The id of the key
-               * @example key_1234
-               */
-              id: string;
-              /**
-               * @description The id of the workspace that owns the api
-               * @example ws_1234
-               */
-              workspaceId: string;
-              /**
-               * @description The name of the api. This is internal and your users will not see this.
-               * @example Unkey - Production
-               */
-              name?: string;
-            };
-          };
-        };
-        /** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
-        400: {
-          content: {
-            "application/json": components["schemas"]["ErrBadRequest"];
-          };
-        };
-        /** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
-        401: {
-          content: {
-            "application/json": components["schemas"]["ErrUnauthorized"];
-          };
-        };
-        /** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
-        403: {
-          content: {
-            "application/json": components["schemas"]["ErrForbidden"];
-          };
-        };
-        /** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
-        404: {
-          content: {
-            "application/json": components["schemas"]["ErrNotFound"];
-          };
-        };
-        /** @description This response is sent when a request conflicts with the current state of the server. */
-        409: {
-          content: {
-            "application/json": components["schemas"]["ErrConflict"];
-          };
-        };
-        /** @description The user has sent too many requests in a given amount of time ("rate limiting") */
-        429: {
-          content: {
-            "application/json": components["schemas"]["ErrTooManyRequests"];
-          };
-        };
-        /** @description The server has encountered a situation it does not know how to handle. */
-        500: {
-          content: {
-            "application/json": components["schemas"]["ErrInternalServerError"];
-          };
-        };
-      };
-    };
-    delete: {
-      parameters: {
-        path: {
-          apiId: string;
-        };
-      };
-      responses: {
-        /** @description The api was successfully deleted, it may take up to 30s for this to take effect in all regions */
-        200: {
-          content: {
-            "application/json": Record<string, never>;
-          };
-        };
-        /** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
-        400: {
-          content: {
-            "application/json": components["schemas"]["ErrBadRequest"];
-          };
-        };
-        /** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
-        401: {
-          content: {
-            "application/json": components["schemas"]["ErrUnauthorized"];
-          };
-        };
-        /** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
-        403: {
-          content: {
-            "application/json": components["schemas"]["ErrForbidden"];
-          };
-        };
-        /** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
-        404: {
-          content: {
-            "application/json": components["schemas"]["ErrNotFound"];
-          };
-        };
-        /** @description This response is sent when a request conflicts with the current state of the server. */
-        409: {
-          content: {
-            "application/json": components["schemas"]["ErrConflict"];
-          };
-        };
-        /** @description The user has sent too many requests in a given amount of time ("rate limiting") */
-        429: {
-          content: {
-            "application/json": components["schemas"]["ErrTooManyRequests"];
-          };
-        };
-        /** @description The server has encountered a situation it does not know how to handle. */
-        500: {
-          content: {
-            "application/json": components["schemas"]["ErrInternalServerError"];
-          };
-        };
-      };
-    };
-  };
-  "/v1/apis/{apiId}/keys": {
-    get: {
-      parameters: {
-        query?: {
-          limit?: number;
-          offset?: number | null;
-          ownerId?: string;
-        };
-        path: {
-          apiId: string;
-        };
-      };
-      responses: {
-        /** @description Keys belonging to the api */
-        200: {
-          content: {
-            "application/json": {
-              keys: components["schemas"]["Key"][];
-              /** @description The total number of keys for this api */
-              total: number;
+              code?: "NOT_FOUND" | "FORBIDDEN" | "USAGE_EXCEEDED" | "RATE_LIMITED" | "UNAUTHORIZED" | "DISABLED" | "INSUFFICIENT_PERMISSIONS";
             };
           };
         };
@@ -2107,6 +1625,14 @@ interface components {
        * ]
        */
       roles?: string[];
+      /**
+       * @description All permissions this key has
+       * @example [
+       *   "domain.dns.create_record",
+       *   "finance.read_receipt"
+       * ]
+       */
+      permissions?: string[];
       /**
        * @description Sets if key is enabled or disabled. Disabled keys are not valid.
        * @example true
@@ -2192,11 +1718,26 @@ interface components {
        * - RATE_LIMITED: the key has been ratelimited
        * - UNAUTHORIZED: the key is not authorized
        * - DISABLED: the key is disabled
+       * - INSUFFICIENT_PERMISSIONS: you do not have the required permissions to perform this action
+       *
        * @enum {string}
        */
-      code?: "NOT_FOUND" | "FORBIDDEN" | "USAGE_EXCEEDED" | "RATE_LIMITED" | "UNAUTHORIZED" | "DISABLED";
+      code?: "NOT_FOUND" | "FORBIDDEN" | "USAGE_EXCEEDED" | "RATE_LIMITED" | "UNAUTHORIZED" | "DISABLED" | "INSUFFICIENT_PERMISSIONS";
       /** @description Sets the key to be enabled or disabled. Disabled keys will not verify. */
       enabled?: boolean;
+      /**
+       * @description A list of all the permissions this key is connected to.
+       * @example [
+       *   "dns.record.update",
+       *   "dns.record.delete"
+       * ]
+       */
+      permissions?: string[];
+      /**
+       * @description The environment of the key, this is what what you set when you crated the key
+       * @example test
+       */
+      environment?: string;
     };
     V1KeysVerifyKeyRequest: {
       /**
@@ -2210,6 +1751,24 @@ interface components {
        * @example sk_1234
        */
       key: string;
+      /** @description Perform RBAC checks */
+      authorization?: {
+        /**
+         * @description A query for which permissions you require
+         * @example {
+         *   "or": [
+         *     {
+         *       "and": [
+         *         "dns.record.read",
+         *         "dns.record.update"
+         *       ]
+         *     },
+         *     "admin"
+         *   ]
+         * }
+         */
+        permissions: Record<string, never>;
+      };
     };
   };
   responses: never;
@@ -2306,7 +1865,17 @@ declare class Unkey {
     get keys(): {
         create: (req: paths["/v1/keys.createKey"]["post"]["requestBody"]["content"]["application/json"]) => Promise<Result<paths["/v1/keys.createKey"]["post"]["responses"]["200"]["content"]["application/json"]>>;
         update: (req: paths["/v1/keys.updateKey"]["post"]["requestBody"]["content"]["application/json"]) => Promise<Result<paths["/v1/keys.updateKey"]["post"]["responses"]["200"]["content"]["application/json"]>>;
-        verify: (req: paths["/v1/keys.verifyKey"]["post"]["requestBody"]["content"]["application/json"]) => Promise<Result<paths["/v1/keys.verifyKey"]["post"]["responses"]["200"]["content"]["application/json"]>>;
+        verify: <TPermission extends string = string>(req: Omit<{
+            apiId?: string | undefined;
+            key: string;
+            authorization?: {
+                permissions: Record<string, never>;
+            } | undefined;
+        }, "authorization"> & {
+            authorization?: {
+                permissions: PermissionQuery<TPermission>;
+            } | undefined;
+        }) => Promise<Result<paths["/v1/keys.verifyKey"]["post"]["responses"]["200"]["content"]["application/json"]>>;
         delete: (req: paths["/v1/keys.deleteKey"]["post"]["requestBody"]["content"]["application/json"]) => Promise<Result<paths["/v1/keys.deleteKey"]["post"]["responses"]["200"]["content"]["application/json"]>>;
         updateRemaining: (req: paths["/v1/keys.updateRemaining"]["post"]["requestBody"]["content"]["application/json"]) => Promise<Result<paths["/v1/keys.updateRemaining"]["post"]["responses"]["200"]["content"]["application/json"]>>;
         get: (req: paths["/v1/keys.getKey"]["get"]["parameters"]["query"]) => Promise<Result<paths["/v1/keys.getKey"]["get"]["responses"]["200"]["content"]["application/json"]>>;
@@ -2368,10 +1937,12 @@ declare function verifyKey(req: string | {
             reset: number;
         } | undefined;
         remaining?: number | undefined;
-        code?: "NOT_FOUND" | "FORBIDDEN" | "USAGE_EXCEEDED" | "RATE_LIMITED" | "UNAUTHORIZED" | "DISABLED" | undefined;
+        code?: "NOT_FOUND" | "FORBIDDEN" | "USAGE_EXCEEDED" | "RATE_LIMITED" | "UNAUTHORIZED" | "DISABLED" | "INSUFFICIENT_PERMISSIONS" | undefined;
         enabled?: boolean | undefined;
+        permissions?: string[] | undefined;
+        environment?: string | undefined;
     };
     error?: undefined;
 }>;
 
-export { ErrorResponse, Unkey, UnkeyOptions, verifyKey };
+export { type ErrorResponse, Unkey, type UnkeyOptions, verifyKey };