diff --git a/demo/nextjs/lib/auth.ts b/demo/nextjs/lib/auth.ts
index dc9ef818..72c629c1 100644
--- a/demo/nextjs/lib/auth.ts
+++ b/demo/nextjs/lib/auth.ts
@@ -8,7 +8,7 @@ import {
twoFactor,
oneTap,
oAuthProxy,
- createAuthEndpoint,
+ openAPI,
} from "better-auth/plugins";
import { reactInvitationEmail } from "./email/invitation";
import { LibsqlDialect } from "@libsql/kysely-libsql";
@@ -18,7 +18,6 @@ import { MysqlDialect } from "kysely";
import { createPool } from "mysql2/promise";
import { nextCookies } from "better-auth/next-js";
import { customSession } from "./auth/plugins/custom-session";
-import { openAPI } from "@better-auth/open-api";
const from = process.env.BETTER_AUTH_EMAIL || "delivered@resend.dev";
const to = process.env.TEST_EMAIL || "";
diff --git a/demo/nextjs/package.json b/demo/nextjs/package.json
index 1720e599..6dfbca50 100644
--- a/demo/nextjs/package.json
+++ b/demo/nextjs/package.json
@@ -11,7 +11,6 @@
"lint": "next lint"
},
"dependencies": {
- "@better-auth/open-api": "workspace:1.0.0-canary.12",
"@better-fetch/fetch": "1.1.12",
"@hookform/resolvers": "^3.9.0",
"@libsql/client": "^0.12.0",
diff --git a/docs/app/docs/[[...slug]]/page.tsx b/docs/app/docs/[[...slug]]/page.tsx
index a0d4fcce..86d90687 100644
--- a/docs/app/docs/[[...slug]]/page.tsx
+++ b/docs/app/docs/[[...slug]]/page.tsx
@@ -14,7 +14,6 @@ import { ForkButton } from "@/components/fork-button";
import Link from "next/link";
import defaultMdxComponents from "fumadocs-ui/mdx";
import { AutoTypeTable } from "fumadocs-typescript/ui";
-import { openapi } from '@/app/source';
export default async function Page({
params,
@@ -74,11 +73,9 @@ export default async function Page({
Features,
ForkButton,
DatabaseTable,
- APIPage: openapi.APIPage,
iframe: (props) => (
),
- APIPage: openapi.APIPage,
}}
/>
@@ -87,48 +84,48 @@ export default async function Page({
}
export async function generateStaticParams() {
- // const res = source.getPages().map((page) => ({
- // slug: page.slugs,
- // }));
+ const res = source.getPages().map((page) => ({
+ slug: page.slugs,
+ }));
return source.generateParams();
}
-// export async function generateMetadata({
-// params,
-// }: { params: Promise<{ slug?: string[] }> }) {
-// const { slug } = await params;
-// const page = source.getPage(slug);
-// if (page == null) notFound();
-// const baseUrl = process.env.NEXT_PUBLIC_URL || process.env.VERCEL_URL;
-// const url = new URL(`${baseUrl}/api/og`);
-// const { title, description } = page.data;
-// const pageSlug = page.file.path;
-// url.searchParams.set("type", "Documentation");
-// url.searchParams.set("mode", "dark");
-// url.searchParams.set("heading", `${title}`);
+export async function generateMetadata({
+ params,
+}: { params: Promise<{ slug?: string[] }> }) {
+ const { slug } = await params;
+ const page = source.getPage(slug);
+ if (page == null) notFound();
+ const baseUrl = process.env.NEXT_PUBLIC_URL || process.env.VERCEL_URL;
+ const url = new URL(`${baseUrl}/api/og`);
+ const { title, description } = page.data;
+ const pageSlug = page.file.path;
+ url.searchParams.set("type", "Documentation");
+ url.searchParams.set("mode", "dark");
+ url.searchParams.set("heading", `${title}`);
-// return {
-// title,
-// description,
-// openGraph: {
-// title,
-// description,
-// type: "website",
-// url: absoluteUrl(`docs/${pageSlug}`),
-// images: [
-// {
-// url: url.toString(),
-// width: 1200,
-// height: 630,
-// alt: title,
-// },
-// ],
-// },
-// twitter: {
-// card: "summary_large_image",
-// title,
-// description,
-// images: [url.toString()],
-// },
-// };
-// }
+ return {
+ title,
+ description,
+ openGraph: {
+ title,
+ description,
+ type: "website",
+ url: absoluteUrl(`docs/${pageSlug}`),
+ images: [
+ {
+ url: url.toString(),
+ width: 1200,
+ height: 630,
+ alt: title,
+ },
+ ],
+ },
+ twitter: {
+ card: "summary_large_image",
+ title,
+ description,
+ images: [url.toString()],
+ },
+ };
+}
diff --git a/docs/app/source.ts b/docs/app/source.ts
index 10809554..ce897f61 100644
--- a/docs/app/source.ts
+++ b/docs/app/source.ts
@@ -6,9 +6,6 @@ import { createOpenAPI } from "fumadocs-openapi/server";
export const source = loader({
baseUrl: "/docs",
source: createMDXSource(docs, meta),
- pageTree: {
- attachFile,
- },
});
export const changelog = loader({
diff --git a/docs/components/sidebar-content.tsx b/docs/components/sidebar-content.tsx
index 933e7d1f..4f249464 100644
--- a/docs/components/sidebar-content.tsx
+++ b/docs/components/sidebar-content.tsx
@@ -877,6 +877,13 @@ export const contents: Content[] = [
),
},
+ {
+ title: "Open API",
+ href: "/docs/plugins/open-api",
+ icon: ()=>(
+
+ )
+ },
{
title: "JWT",
icon: () => (
diff --git a/docs/content/docs/(api)/account/link-social.mdx b/docs/content/docs/(api)/account/link-social.mdx
deleted file mode 100644
index cfa14e96..00000000
--- a/docs/content/docs/(api)/account/link-social.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Link social account
-full: true
-_openapi:
- method: POST
- route: /link-social
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/account/list-accounts.mdx b/docs/content/docs/(api)/account/list-accounts.mdx
deleted file mode 100644
index 134345ab..00000000
--- a/docs/content/docs/(api)/account/list-accounts.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: List all accounts
-full: true
-_openapi:
- method: GET
- route: /list-accounts
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/callback/callback.mdx b/docs/content/docs/(api)/callback/callback.mdx
deleted file mode 100644
index 8ff0ef7a..00000000
--- a/docs/content/docs/(api)/callback/callback.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Callback
-full: true
-_openapi:
- method: GET
- route: /callback/:id
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/email--verification/send-verification-email.mdx b/docs/content/docs/(api)/email--verification/send-verification-email.mdx
deleted file mode 100644
index 3f74b9b3..00000000
--- a/docs/content/docs/(api)/email--verification/send-verification-email.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Send verification email
-full: true
-_openapi:
- method: POST
- route: /send-verification-email
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/email--verification/verify-email.mdx b/docs/content/docs/(api)/email--verification/verify-email.mdx
deleted file mode 100644
index 01c3de00..00000000
--- a/docs/content/docs/(api)/email--verification/verify-email.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Verify email
-full: true
-_openapi:
- method: GET
- route: /verify-email
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/forget--password/forget-password.mdx b/docs/content/docs/(api)/forget--password/forget-password.mdx
deleted file mode 100644
index ee7a1e05..00000000
--- a/docs/content/docs/(api)/forget--password/forget-password.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Forget password
-full: true
-_openapi:
- method: POST
- route: /forget-password
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/forget--password/reset-password-token.mdx b/docs/content/docs/(api)/forget--password/reset-password-token.mdx
deleted file mode 100644
index bbcbc17f..00000000
--- a/docs/content/docs/(api)/forget--password/reset-password-token.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Reset password with token
-full: true
-_openapi:
- method: GET
- route: /reset-password/:token
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/forget--password/reset-password.mdx b/docs/content/docs/(api)/forget--password/reset-password.mdx
deleted file mode 100644
index a39e15bd..00000000
--- a/docs/content/docs/(api)/forget--password/reset-password.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Reset password
-full: true
-_openapi:
- method: POST
- route: /reset-password
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/sessions/get-session.mdx b/docs/content/docs/(api)/sessions/get-session.mdx
deleted file mode 100644
index 60bbdb3a..00000000
--- a/docs/content/docs/(api)/sessions/get-session.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Get current session
-full: true
-_openapi:
- method: GET
- route: /get-session
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/sessions/list-sessions.mdx b/docs/content/docs/(api)/sessions/list-sessions.mdx
deleted file mode 100644
index ca554b0e..00000000
--- a/docs/content/docs/(api)/sessions/list-sessions.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: List all sessions
-full: true
-_openapi:
- method: GET
- route: /list-sessions
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/sessions/revoke-other-sessions.mdx b/docs/content/docs/(api)/sessions/revoke-other-sessions.mdx
deleted file mode 100644
index 1dd7c8c0..00000000
--- a/docs/content/docs/(api)/sessions/revoke-other-sessions.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Revoke other sessions
-full: true
-_openapi:
- method: POST
- route: /revoke-other-sessions
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/sessions/revoke-session.mdx b/docs/content/docs/(api)/sessions/revoke-session.mdx
deleted file mode 100644
index 05df5273..00000000
--- a/docs/content/docs/(api)/sessions/revoke-session.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Revoke a session
-full: true
-_openapi:
- method: POST
- route: /revoke-session
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/sessions/revoke-sessions.mdx b/docs/content/docs/(api)/sessions/revoke-sessions.mdx
deleted file mode 100644
index 98552ee0..00000000
--- a/docs/content/docs/(api)/sessions/revoke-sessions.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Revoke all sessions
-full: true
-_openapi:
- method: POST
- route: /revoke-sessions
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/sign-in/sign-in-email.mdx b/docs/content/docs/(api)/sign-in/sign-in-email.mdx
deleted file mode 100644
index e00d93f7..00000000
--- a/docs/content/docs/(api)/sign-in/sign-in-email.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Sign in with email
-full: true
-_openapi:
- method: POST
- route: /sign-in/email
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/sign-in/sign-in-social.mdx b/docs/content/docs/(api)/sign-in/sign-in-social.mdx
deleted file mode 100644
index 8e8c0ed6..00000000
--- a/docs/content/docs/(api)/sign-in/sign-in-social.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Sign in with social account
-full: true
-_openapi:
- method: POST
- route: /sign-in/social
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/sign-out/sign-out.mdx b/docs/content/docs/(api)/sign-out/sign-out.mdx
deleted file mode 100644
index 39cc4c11..00000000
--- a/docs/content/docs/(api)/sign-out/sign-out.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Sign out
-full: true
-_openapi:
- method: POST
- route: /sign-out
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/sign-up/sign-up-email.mdx b/docs/content/docs/(api)/sign-up/sign-up-email.mdx
deleted file mode 100644
index 3c8c0504..00000000
--- a/docs/content/docs/(api)/sign-up/sign-up-email.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Sign up with email
-full: true
-_openapi:
- method: POST
- route: /sign-up/email
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/update-user/change-email.mdx b/docs/content/docs/(api)/update-user/change-email.mdx
deleted file mode 100644
index 003fb8f5..00000000
--- a/docs/content/docs/(api)/update-user/change-email.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Change email
-full: true
-_openapi:
- method: POST
- route: /change-email
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/update-user/change-password.mdx b/docs/content/docs/(api)/update-user/change-password.mdx
deleted file mode 100644
index a6343dbf..00000000
--- a/docs/content/docs/(api)/update-user/change-password.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Change password
-full: true
-_openapi:
- method: POST
- route: /change-password
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/update-user/delete-user.mdx b/docs/content/docs/(api)/update-user/delete-user.mdx
deleted file mode 100644
index 05d9cd96..00000000
--- a/docs/content/docs/(api)/update-user/delete-user.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Delete user
-full: true
-_openapi:
- method: POST
- route: /delete-user
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/update-user/set-password.mdx b/docs/content/docs/(api)/update-user/set-password.mdx
deleted file mode 100644
index b9e89689..00000000
--- a/docs/content/docs/(api)/update-user/set-password.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Set password
-full: true
-_openapi:
- method: POST
- route: /set-password
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/(api)/update-user/update-user.mdx b/docs/content/docs/(api)/update-user/update-user.mdx
deleted file mode 100644
index d9867b61..00000000
--- a/docs/content/docs/(api)/update-user/update-user.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Update user
-full: true
-_openapi:
- method: POST
- route: /update-user
- toc: []
- structuredData:
- headings: []
- contents: []
----
-
-
\ No newline at end of file
diff --git a/docs/content/docs/plugins/open-api.mdx b/docs/content/docs/plugins/open-api.mdx
new file mode 100644
index 00000000..daec16fc
--- /dev/null
+++ b/docs/content/docs/plugins/open-api.mdx
@@ -0,0 +1,38 @@
+---
+title: Open API
+description: Open API reference for Better Auth.
+---
+
+This is a plugin that provides an Open API reference for Better Auth. It shows all endpoints added by plugins and the core. It also provides a way to test the endpoints. It uses [Scalar](https://scalar.com/) to display the Open API reference.
+
+
+
+This plugin is still in the early stages of development. We are working on adding more features to it and filling in the gaps.
+
+
+
+## Installation
+
+
+
+ ### Add the plugin to your **auth** config
+ ```ts title="auth.ts"
+ import { betterAuth } from "better-auth"
+ import { openAPI } from "better-auth/plugins"
+
+ export const auth = betterAuth({
+ plugins: [ // [!code highlight]
+ openAPI(), // [!code highlight]
+ ] // [!code highlight]
+ })
+ ```
+
+
+ ### Navigate to `/api/auth/reference` to view the Open API reference
+
+ Each plugin endpoints are grouped by the plugin name. The core endpoints are grouped under the `Default` group. And Model schemas are grouped under the `Models` group.
+
+ 
+
+
+
diff --git a/docs/openapi.json b/docs/openapi.json
deleted file mode 100644
index cce6924a..00000000
--- a/docs/openapi.json
+++ /dev/null
@@ -1,7266 +0,0 @@
-{
- "openapi": "3.0.0",
- "info": {
- "title": "Unkey Api",
- "version": "1.0.0"
- },
- "servers": [
- {
- "url": "https://api.unkey.dev",
- "description": "Production"
- },
- {
- "url": "https://example.com/api/v1",
- "description": "Example API"
- }
- ],
- "x-speakeasy-retries": {
- "strategy": "backoff",
- "backoff": {
- "initialInterval": 50,
- "maxInterval": 1000,
- "maxElapsedTime": 30000,
- "exponent": 1.5
- },
- "statusCodes": [
- "5XX"
- ],
- "retryConnectionErrors": true
- },
- "components": {
- "securitySchemes": {
- "bearerAuth": {
- "bearerFormat": "root key",
- "type": "http",
- "scheme": "bearer"
- }
- },
- "schemas": {
- "ErrBadRequest": {
- "type": "object",
- "properties": {
- "error": {
- "type": "object",
- "properties": {
- "code": {
- "type": "string",
- "enum": [
- "BAD_REQUEST"
- ],
- "description": "A machine readable error code.",
- "example": "BAD_REQUEST"
- },
- "docs": {
- "type": "string",
- "description": "A link to our documentation with more details about this error code",
- "example": "https://unkey.dev/docs/api-reference/errors/code/BAD_REQUEST"
- },
- "message": {
- "type": "string",
- "description": "A human readable explanation of what went wrong"
- },
- "requestId": {
- "type": "string",
- "description": "Please always include the requestId in your error report",
- "example": "req_1234"
- }
- },
- "required": [
- "code",
- "docs",
- "message",
- "requestId"
- ]
- }
- },
- "required": [
- "error"
- ]
- },
- "ErrUnauthorized": {
- "type": "object",
- "properties": {
- "error": {
- "type": "object",
- "properties": {
- "code": {
- "type": "string",
- "enum": [
- "UNAUTHORIZED"
- ],
- "description": "A machine readable error code.",
- "example": "UNAUTHORIZED"
- },
- "docs": {
- "type": "string",
- "description": "A link to our documentation with more details about this error code",
- "example": "https://unkey.dev/docs/api-reference/errors/code/UNAUTHORIZED"
- },
- "message": {
- "type": "string",
- "description": "A human readable explanation of what went wrong"
- },
- "requestId": {
- "type": "string",
- "description": "Please always include the requestId in your error report",
- "example": "req_1234"
- }
- },
- "required": [
- "code",
- "docs",
- "message",
- "requestId"
- ]
- }
- },
- "required": [
- "error"
- ]
- },
- "ErrForbidden": {
- "type": "object",
- "properties": {
- "error": {
- "type": "object",
- "properties": {
- "code": {
- "type": "string",
- "enum": [
- "FORBIDDEN"
- ],
- "description": "A machine readable error code.",
- "example": "FORBIDDEN"
- },
- "docs": {
- "type": "string",
- "description": "A link to our documentation with more details about this error code",
- "example": "https://unkey.dev/docs/api-reference/errors/code/FORBIDDEN"
- },
- "message": {
- "type": "string",
- "description": "A human readable explanation of what went wrong"
- },
- "requestId": {
- "type": "string",
- "description": "Please always include the requestId in your error report",
- "example": "req_1234"
- }
- },
- "required": [
- "code",
- "docs",
- "message",
- "requestId"
- ]
- }
- },
- "required": [
- "error"
- ]
- },
- "ErrNotFound": {
- "type": "object",
- "properties": {
- "error": {
- "type": "object",
- "properties": {
- "code": {
- "type": "string",
- "enum": [
- "NOT_FOUND"
- ],
- "description": "A machine readable error code.",
- "example": "NOT_FOUND"
- },
- "docs": {
- "type": "string",
- "description": "A link to our documentation with more details about this error code",
- "example": "https://unkey.dev/docs/api-reference/errors/code/NOT_FOUND"
- },
- "message": {
- "type": "string",
- "description": "A human readable explanation of what went wrong"
- },
- "requestId": {
- "type": "string",
- "description": "Please always include the requestId in your error report",
- "example": "req_1234"
- }
- },
- "required": [
- "code",
- "docs",
- "message",
- "requestId"
- ]
- }
- },
- "required": [
- "error"
- ]
- },
- "ErrConflict": {
- "type": "object",
- "properties": {
- "error": {
- "type": "object",
- "properties": {
- "code": {
- "type": "string",
- "enum": [
- "CONFLICT"
- ],
- "description": "A machine readable error code.",
- "example": "CONFLICT"
- },
- "docs": {
- "type": "string",
- "description": "A link to our documentation with more details about this error code",
- "example": "https://unkey.dev/docs/api-reference/errors/code/CONFLICT"
- },
- "message": {
- "type": "string",
- "description": "A human readable explanation of what went wrong"
- },
- "requestId": {
- "type": "string",
- "description": "Please always include the requestId in your error report",
- "example": "req_1234"
- }
- },
- "required": [
- "code",
- "docs",
- "message",
- "requestId"
- ]
- }
- },
- "required": [
- "error"
- ]
- },
- "ErrTooManyRequests": {
- "type": "object",
- "properties": {
- "error": {
- "type": "object",
- "properties": {
- "code": {
- "type": "string",
- "enum": [
- "TOO_MANY_REQUESTS"
- ],
- "description": "A machine readable error code.",
- "example": "TOO_MANY_REQUESTS"
- },
- "docs": {
- "type": "string",
- "description": "A link to our documentation with more details about this error code",
- "example": "https://unkey.dev/docs/api-reference/errors/code/TOO_MANY_REQUESTS"
- },
- "message": {
- "type": "string",
- "description": "A human readable explanation of what went wrong"
- },
- "requestId": {
- "type": "string",
- "description": "Please always include the requestId in your error report",
- "example": "req_1234"
- }
- },
- "required": [
- "code",
- "docs",
- "message",
- "requestId"
- ]
- }
- },
- "required": [
- "error"
- ]
- },
- "ErrInternalServerError": {
- "type": "object",
- "properties": {
- "error": {
- "type": "object",
- "properties": {
- "code": {
- "type": "string",
- "enum": [
- "INTERNAL_SERVER_ERROR"
- ],
- "description": "A machine readable error code.",
- "example": "INTERNAL_SERVER_ERROR"
- },
- "docs": {
- "type": "string",
- "description": "A link to our documentation with more details about this error code",
- "example": "https://unkey.dev/docs/api-reference/errors/code/INTERNAL_SERVER_ERROR"
- },
- "message": {
- "type": "string",
- "description": "A human readable explanation of what went wrong"
- },
- "requestId": {
- "type": "string",
- "description": "Please always include the requestId in your error report",
- "example": "req_1234"
- }
- },
- "required": [
- "code",
- "docs",
- "message",
- "requestId"
- ]
- }
- },
- "required": [
- "error"
- ]
- },
- "Key": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "description": "The id of the key",
- "example": "key_1234"
- },
- "start": {
- "type": "string",
- "description": "The first few characters of the key to visually identify it",
- "example": "sk_5j1"
- },
- "workspaceId": {
- "type": "string",
- "description": "The id of the workspace that owns the key",
- "example": "ws_1234"
- },
- "apiId": {
- "type": "string",
- "description": "The id of the api that this key is for",
- "example": "api_1234"
- },
- "name": {
- "type": "string",
- "description": "The name of the key, give keys a name to easily identify their purpose",
- "example": "Customer X"
- },
- "ownerId": {
- "type": "string",
- "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"
- },
- "meta": {
- "type": "object",
- "additionalProperties": {
- "nullable": true
- },
- "description": "Any additional metadata you want to store with the key",
- "example": {
- "roles": [
- "admin",
- "user"
- ],
- "stripeCustomerId": "cus_1234"
- }
- },
- "createdAt": {
- "type": "integer",
- "description": "The unix timestamp in milliseconds when the key was created",
- "example": 0
- },
- "updatedAt": {
- "type": "integer",
- "description": "The unix timestamp in milliseconds when the key was last updated",
- "example": 0
- },
- "expires": {
- "type": "integer",
- "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
- },
- "remaining": {
- "type": "integer",
- "description": "The number of requests that can be made with this key before it becomes invalid. If this field is null or undefined, the key has no request limit.",
- "example": 1000
- },
- "refill": {
- "type": "object",
- "properties": {
- "interval": {
- "type": "string",
- "enum": [
- "daily",
- "monthly"
- ],
- "description": "Determines the rate at which verifications will be refilled.",
- "example": "daily"
- },
- "amount": {
- "type": "integer",
- "description": "Resets `remaining` to this value every interval.",
- "example": 100
- },
- "lastRefillAt": {
- "type": "integer",
- "description": "The unix timestamp in miliseconds when the key was last refilled.",
- "example": 100
- }
- },
- "required": [
- "interval",
- "amount"
- ],
- "description": "Unkey allows you to refill remaining verifications on a key on a regular interval.",
- "example": {
- "interval": "daily",
- "amount": 10
- }
- },
- "ratelimit": {
- "type": "object",
- "properties": {
- "async": {
- "type": "boolean",
- "description": ""
- },
- "type": {
- "type": "string",
- "enum": [
- "fast",
- "consistent"
- ],
- "description": "Fast ratelimiting doesn't add latency, while consistent ratelimiting is more accurate.",
- "externalDocs": {
- "description": "Learn more",
- "url": "https://unkey.dev/docs/features/ratelimiting"
- }
- },
- "limit": {
- "type": "integer",
- "minimum": 1,
- "description": "The total amount of burstable requests."
- },
- "refillRate": {
- "type": "integer",
- "minimum": 1,
- "description": "How many tokens to refill during each refillInterval."
- },
- "refillInterval": {
- "type": "integer",
- "minimum": 1,
- "description": "Determines the speed at which tokens are refilled, in milliseconds."
- },
- "duration": {
- "type": "integer",
- "minimum": 1,
- "description": "The duration of the ratelimit window, in milliseconds."
- }
- },
- "required": [
- "async",
- "limit",
- "duration"
- ],
- "description": "Unkey comes with per-key ratelimiting out of the box.",
- "example": {
- "async": true,
- "limit": 10,
- "duration": 60
- }
- },
- "roles": {
- "type": "array",
- "items": {
- "type": "string"
- },
- "description": "All roles this key belongs to",
- "example": [
- "admin",
- "finance"
- ]
- },
- "permissions": {
- "type": "array",
- "items": {
- "type": "string"
- },
- "description": "All permissions this key has",
- "example": [
- "domain.dns.create_record",
- "finance.read_receipt"
- ]
- },
- "enabled": {
- "type": "boolean",
- "description": "Sets if key is enabled or disabled. Disabled keys are not valid.",
- "example": true
- },
- "plaintext": {
- "type": "string",
- "description": "The key in plaintext"
- },
- "identity": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "description": "The id of the identity"
- },
- "externalId": {
- "type": "string",
- "description": "The external id of the identity"
- },
- "meta": {
- "type": "object",
- "additionalProperties": {
- "nullable": true
- },
- "description": "Any additional metadata attached to the identity"
- }
- },
- "required": [
- "id",
- "externalId"
- ],
- "description": "The identity of the key"
- }
- },
- "required": [
- "id",
- "start",
- "workspaceId",
- "createdAt"
- ]
- },
- "V1KeysVerifyKeyResponse": {
- "type": "object",
- "properties": {
- "keyId": {
- "type": "string",
- "description": "The id of the key",
- "example": "key_1234"
- },
- "valid": {
- "type": "boolean",
- "description": "Whether the key is valid or not.\nA key could be invalid for a number of reasons, for example if it has expired, has no more verifications left or if it has been deleted.",
- "example": true
- },
- "name": {
- "type": "string",
- "description": "The name of the key, give keys a name to easily identifiy their purpose",
- "example": "Customer X"
- },
- "ownerId": {
- "type": "string",
- "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"
- },
- "meta": {
- "type": "object",
- "additionalProperties": {
- "nullable": true
- },
- "description": "Any additional metadata you want to store with the key",
- "example": {
- "roles": [
- "admin",
- "user"
- ],
- "stripeCustomerId": "cus_1234"
- }
- },
- "expires": {
- "type": "integer",
- "description": "The unix timestamp in milliseconds when the key will expire. If this field is null or undefined, the key is not expiring.",
- "example": 123
- },
- "ratelimit": {
- "type": "object",
- "properties": {
- "limit": {
- "type": "integer",
- "description": "Maximum number of requests that can be made inside a window",
- "example": 10
- },
- "remaining": {
- "type": "integer",
- "description": "Remaining requests after this verification",
- "example": 9
- },
- "reset": {
- "type": "integer",
- "description": "Unix timestamp in milliseconds when the ratelimit will reset",
- "example": 3600000
- }
- },
- "required": [
- "limit",
- "remaining",
- "reset"
- ],
- "description": "The ratelimit configuration for this key. If this field is null or undefined, the key has no ratelimit.",
- "example": {
- "limit": 10,
- "remaining": 9,
- "reset": 3600000
- }
- },
- "remaining": {
- "type": "integer",
- "description": "The number of requests that can be made with this key before it becomes invalid. If this field is null or undefined, the key has no request limit.",
- "example": 1000
- },
- "code": {
- "type": "string",
- "enum": [
- "VALID",
- "NOT_FOUND",
- "FORBIDDEN",
- "USAGE_EXCEEDED",
- "RATE_LIMITED",
- "UNAUTHORIZED",
- "DISABLED",
- "INSUFFICIENT_PERMISSIONS",
- "EXPIRED"
- ],
- "description": "A machine readable code why the key is not valid.\nPossible values are:\n- VALID: the key is valid and you should proceed\n- NOT_FOUND: the key does not exist or has expired\n- FORBIDDEN: the key is not allowed to access the api\n- USAGE_EXCEEDED: the key has exceeded its request limit\n- RATE_LIMITED: the key has been ratelimited\n- UNAUTHORIZED: the key is not authorized\n- DISABLED: the key is disabled\n- INSUFFICIENT_PERMISSIONS: you do not have the required permissions to perform this action\n- EXPIRED: The key was only valid for a certain time and has expired.\n"
- },
- "enabled": {
- "type": "boolean",
- "description": "Sets the key to be enabled or disabled. Disabled keys will not verify."
- },
- "permissions": {
- "type": "array",
- "items": {
- "type": "string"
- },
- "description": "A list of all the permissions this key is connected to.",
- "example": [
- "dns.record.update",
- "dns.record.delete"
- ]
- },
- "environment": {
- "type": "string",
- "description": "The environment of the key, this is what what you set when you crated the key",
- "example": "test"
- },
- "identity": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string"
- },
- "externalId": {
- "type": "string"
- },
- "meta": {
- "type": "object",
- "additionalProperties": {
- "nullable": true
- }
- }
- },
- "required": [
- "id",
- "externalId",
- "meta"
- ],
- "description": "The associated identity of this key."
- }
- },
- "required": [
- "valid",
- "code"
- ]
- },
- "PermissionQuery": {
- "nullable": true,
- "description": "A query for which permissions you require",
- "oneOf": [
- {
- "title": "LiteralClause",
- "type": "string"
- },
- {
- "title": "And",
- "type": "object",
- "required": [
- "and"
- ],
- "properties": {
- "and": {
- "type": "array",
- "items": {
- "$ref": "#/components/schemas/PermissionQuery"
- }
- }
- }
- },
- {
- "title": "Or",
- "type": "object",
- "required": [
- "or"
- ],
- "properties": {
- "or": {
- "type": "array",
- "items": {
- "$ref": "#/components/schemas/PermissionQuery"
- }
- }
- }
- }
- ]
- },
- "V1KeysVerifyKeyRequest": {
- "type": "object",
- "properties": {
- "apiId": {
- "type": "string",
- "description": "The id of the api where the key belongs to. This is optional for now but will be required soon.\nThe key will be verified against the api's configuration. If the key does not belong to the api, the verification will fail.",
- "example": "api_1234"
- },
- "key": {
- "type": "string",
- "minLength": 1,
- "description": "The key to verify",
- "example": "sk_1234"
- },
- "authorization": {
- "type": "object",
- "properties": {
- "permissions": {
- "$ref": "#/components/schemas/PermissionQuery"
- }
- },
- "description": "Perform RBAC checks"
- },
- "ratelimit": {
- "type": "object",
- "properties": {
- "cost": {
- "type": "integer",
- "minimum": 0,
- "default": 1,
- "description": "Override how many tokens are deducted during the ratelimit operation."
- }
- },
- "description": "Use 'ratelimits' with `[{ name: \"default\", cost: 2}]`",
- "deprecated": true
- },
- "ratelimits": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "minLength": 1,
- "description": "The name of the ratelimit.",
- "example": "tokens"
- },
- "cost": {
- "type": "integer",
- "minimum": 0,
- "default": 1,
- "description": "Optionally override how expensive this operation is and how many tokens are deducted from the current limit."
- },
- "limit": {
- "type": "integer",
- "description": "Optionally override the limit."
- },
- "duration": {
- "type": "integer",
- "description": "Optionally override the ratelimit window duration."
- }
- },
- "required": [
- "name"
- ]
- },
- "description": "You can check against multiple ratelimits when verifying a key. Let's say you are building an app that uses AI under the hood and you want to limit your customers to 500 requests per hour, but also ensure they use up less than 20k tokens per day.\n ",
- "externalDocs": {
- "url": "https://www.unkey.com/docs/concepts/identities/ratelimits"
- },
- "example": [
- {
- "name": "requests",
- "limit": 500,
- "duration": 3600000
- },
- {
- "name": "tokens",
- "limit": 20000,
- "duration": 86400000
- }
- ]
- }
- },
- "required": [
- "key"
- ]
- }
- },
- "parameters": {}
- },
- "paths": {
- "/v1/liveness": {
- "get": {
- "tags": [
- "liveness"
- ],
- "operationId": "v1.liveness",
- "responses": {
- "200": {
- "description": "The configured services and their status",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "status": {
- "type": "string",
- "description": "The status of the server"
- },
- "services": {
- "type": "object",
- "properties": {
- "metrics": {
- "type": "string",
- "description": "The name of the connected metrics service",
- "example": "AxiomMetrics"
- },
- "logger": {
- "type": "string",
- "description": "The name of the connected logger service",
- "example": "AxiomLogger or ConsoleLogger"
- },
- "ratelimit": {
- "type": "string",
- "description": "The name of the connected ratelimit service"
- },
- "usagelimit": {
- "type": "string",
- "description": "The name of the connected usagelimit service"
- },
- "analytics": {
- "type": "string",
- "description": "The name of the connected analytics service"
- }
- },
- "required": [
- "metrics",
- "logger",
- "ratelimit",
- "usagelimit",
- "analytics"
- ]
- }
- },
- "required": [
- "status",
- "services"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/keys.getKey": {
- "get": {
- "tags": [
- "keys"
- ],
- "operationId": "getKey",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "parameters": [
- {
- "schema": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the key to fetch",
- "example": "key_1234"
- },
- "required": true,
- "name": "keyId",
- "in": "query"
- },
- {
- "schema": {
- "type": "boolean",
- "nullable": true,
- "description": "Decrypt and display the raw key. Only possible if the key was encrypted when generated."
- },
- "required": false,
- "name": "decrypt",
- "in": "query"
- }
- ],
- "responses": {
- "200": {
- "description": "The configuration for a single key",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/Key"
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/keys.deleteKey": {
- "post": {
- "tags": [
- "keys"
- ],
- "operationId": "deleteKey",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "keyId": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the key to revoke",
- "example": "key_1234"
- }
- },
- "required": [
- "keyId"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "The key was successfully revoked, it may take up to 30s for this to take effect in all regions",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {}
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/keys.createKey": {
- "post": {
- "tags": [
- "keys"
- ],
- "operationId": "createKey",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "apiId": {
- "type": "string",
- "description": "Choose an `API` where this key should be created.",
- "example": "api_123"
- },
- "prefix": {
- "type": "string",
- "maxLength": 16,
- "description": "To make it easier for your users to understand which product an api key belongs to, you can add prefix them.\n\nFor example Stripe famously prefixes their customer ids with cus_ or their api keys with sk_live_.\n\nThe underscore is automatically added if you are defining a prefix, for example: \"prefix\": \"abc\" will result in a key like abc_xxxxxxxxx\n"
- },
- "name": {
- "type": "string",
- "description": "The name for your Key. This is not customer facing.",
- "example": "my key"
- },
- "byteLength": {
- "type": "integer",
- "minimum": 16,
- "maximum": 255,
- "default": 16,
- "description": "The byte length used to generate your key determines its entropy as well as its length. Higher is better, but keys become longer and more annoying to handle. The default is 16 bytes, or 2^^128 possible combinations."
- },
- "ownerId": {
- "type": "string",
- "description": "Deprecated, use `externalId`",
- "deprecated": true,
- "example": "team_123"
- },
- "externalId": {
- "type": "string",
- "description": "Your user's Id. This will provide a link between Unkey and your customer record.\nWhen validating a key, we will return this back to you, so you can clearly identify your user from their api key.",
- "example": "team_123"
- },
- "meta": {
- "type": "object",
- "additionalProperties": {
- "nullable": true
- },
- "description": "This is a place for dynamic meta data, anything that feels useful for you should go here",
- "example": {
- "billingTier": "PRO",
- "trialEnds": "2023-06-16T17:16:37.161Z"
- }
- },
- "roles": {
- "type": "array",
- "items": {
- "type": "string",
- "minLength": 1,
- "maxLength": 512
- },
- "description": "A list of roles that this key should have. If the role does not exist, an error is thrown",
- "example": [
- "admin",
- "finance"
- ]
- },
- "permissions": {
- "type": "array",
- "items": {
- "type": "string",
- "minLength": 1,
- "maxLength": 512
- },
- "description": "A list of permissions that this key should have. If the permission does not exist, an error is thrown",
- "example": [
- "domains.create_record",
- "say_hello"
- ]
- },
- "expires": {
- "type": "integer",
- "description": "You can auto expire keys by providing a unix timestamp in milliseconds. Once Keys expire they will automatically be disabled and are no longer valid unless you enable them again.",
- "example": 1623869797161
- },
- "remaining": {
- "type": "integer",
- "description": "You can limit the number of requests a key can make. Once a key reaches 0 remaining requests, it will automatically be disabled and is no longer valid unless you update it.",
- "example": 1000,
- "externalDocs": {
- "description": "Learn more",
- "url": "https://unkey.dev/docs/features/remaining"
- }
- },
- "refill": {
- "type": "object",
- "properties": {
- "interval": {
- "type": "string",
- "enum": [
- "daily",
- "monthly"
- ],
- "description": "Unkey will automatically refill verifications at the set interval."
- },
- "amount": {
- "type": "integer",
- "minimum": 0,
- "exclusiveMinimum": true,
- "description": "The number of verifications to refill for each occurrence is determined individually for each key."
- }
- },
- "required": [
- "interval",
- "amount"
- ],
- "description": "Unkey enables you to refill verifications for each key at regular intervals.",
- "example": {
- "interval": "daily",
- "amount": 100
- }
- },
- "ratelimit": {
- "type": "object",
- "properties": {
- "async": {
- "type": "boolean",
- "default": true,
- "description": "Async will return a response immediately, lowering latency at the cost of accuracy. Will be required soon.",
- "externalDocs": {
- "description": "Learn more",
- "url": "https://unkey.dev/docs/features/ratelimiting"
- }
- },
- "type": {
- "type": "string",
- "enum": [
- "fast",
- "consistent"
- ],
- "default": "fast",
- "description": "Deprecated, used `async`. Fast ratelimiting doesn't add latency, while consistent ratelimiting is more accurate.",
- "externalDocs": {
- "description": "Learn more",
- "url": "https://unkey.dev/docs/features/ratelimiting"
- },
- "deprecated": true
- },
- "limit": {
- "type": "integer",
- "minimum": 1,
- "description": "The total amount of requests in a given interval."
- },
- "duration": {
- "type": "integer",
- "minimum": 1000,
- "description": "The window duration in milliseconds. Will be required soon.",
- "example": 60000
- },
- "refillRate": {
- "type": "integer",
- "minimum": 1,
- "description": "How many tokens to refill during each refillInterval.",
- "deprecated": true
- },
- "refillInterval": {
- "type": "integer",
- "minimum": 1,
- "description": "The refill timeframe, in milliseconds.",
- "deprecated": true
- }
- },
- "required": [
- "limit"
- ],
- "description": "Unkey comes with per-key fixed-window ratelimiting out of the box.",
- "example": {
- "type": "fast",
- "limit": 10,
- "duration": 60000
- }
- },
- "enabled": {
- "type": "boolean",
- "default": true,
- "description": "Sets if key is enabled or disabled. Disabled keys are not valid.",
- "example": false
- },
- "environment": {
- "type": "string",
- "maxLength": 256,
- "description": "Environments allow you to divide your keyspace.\n\nSome applications like Stripe, Clerk, WorkOS and others have a concept of \"live\" and \"test\" keys to\ngive the developer a way to develop their own application without the risk of modifying real world\nresources.\n\nWhen you set an environment, we will return it back to you when validating the key, so you can\nhandle it correctly.\n "
- }
- },
- "required": [
- "apiId"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "The configuration for an api",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "keyId": {
- "type": "string",
- "description": "The id of the key. This is not a secret and can be stored as a reference if you wish. You need the keyId to update or delete a key later.",
- "example": "key_123"
- },
- "key": {
- "type": "string",
- "description": "The newly created api key, do not store this on your own system but pass it along to your user.",
- "example": "prefix_xxxxxxxxx"
- }
- },
- "required": [
- "keyId",
- "key"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/keys.verifyKey": {
- "post": {
- "tags": [
- "keys"
- ],
- "operationId": "verifyKey",
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/V1KeysVerifyKeyRequest"
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "The verification result",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/V1KeysVerifyKeyResponse"
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/keys.updateKey": {
- "post": {
- "tags": [
- "keys"
- ],
- "operationId": "updateKey",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "keyId": {
- "type": "string",
- "description": "The id of the key you want to modify",
- "example": "key_123"
- },
- "name": {
- "type": "string",
- "nullable": true,
- "description": "The name of the key",
- "example": "Customer X"
- },
- "ownerId": {
- "type": "string",
- "nullable": true,
- "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"
- },
- "meta": {
- "type": "object",
- "nullable": true,
- "additionalProperties": {
- "nullable": true
- },
- "description": "Any additional metadata you want to store with the key",
- "example": {
- "roles": [
- "admin",
- "user"
- ],
- "stripeCustomerId": "cus_1234"
- }
- },
- "expires": {
- "type": "integer",
- "nullable": true,
- "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
- },
- "ratelimit": {
- "type": "object",
- "nullable": true,
- "properties": {
- "type": {
- "type": "string",
- "enum": [
- "fast",
- "consistent"
- ],
- "description": "Fast ratelimiting doesn't add latency, while consistent ratelimiting is more accurate.\nDeprecated, use 'async' instead",
- "deprecated": true,
- "externalDocs": {
- "description": "Learn more",
- "url": "https://unkey.dev/docs/features/ratelimiting"
- }
- },
- "async": {
- "type": "boolean",
- "default": false,
- "description": "Asnyc ratelimiting doesn't add latency, while sync ratelimiting is slightly more accurate.",
- "externalDocs": {
- "description": "Learn more",
- "url": "https://unkey.dev/docs/features/ratelimiting"
- }
- },
- "limit": {
- "type": "integer",
- "minimum": 1,
- "description": "The total amount of requests allowed in a single window."
- },
- "refillRate": {
- "type": "integer",
- "minimum": 1,
- "description": "How many tokens to refill during each refillInterval.\nDeprecated, use 'limit' instead.",
- "deprecated": true
- },
- "refillInterval": {
- "type": "integer",
- "minimum": 1,
- "description": "Determines the speed at which tokens are refilled, in milliseconds.\nDeprecated, use 'duration'",
- "deprecated": true
- },
- "duration": {
- "type": "integer",
- "minimum": 1,
- "description": "The duration of each ratelimit window, in milliseconds.\nThis field will become required in a future version."
- }
- },
- "required": [
- "limit"
- ],
- "description": "Unkey comes with per-key ratelimiting out of the box. Set `null` to disable.",
- "example": {
- "type": "fast",
- "limit": 10,
- "refillRate": 1,
- "refillInterval": 60
- }
- },
- "remaining": {
- "type": "integer",
- "nullable": true,
- "description": "The number of requests that can be made with this key before it becomes invalid. Set `null` to disable.",
- "example": 1000
- },
- "refill": {
- "type": "object",
- "nullable": true,
- "properties": {
- "interval": {
- "type": "string",
- "enum": [
- "daily",
- "monthly"
- ],
- "description": "Unkey will automatically refill verifications at the set interval. If null is used the refill functionality will be removed from the key."
- },
- "amount": {
- "type": "integer",
- "minimum": 1,
- "description": "The amount of verifications to refill for each occurrence is determined individually for each key."
- }
- },
- "required": [
- "interval",
- "amount"
- ],
- "description": "Unkey enables you to refill verifications for each key at regular intervals.",
- "example": {
- "interval": "daily",
- "amount": 100
- }
- },
- "enabled": {
- "type": "boolean",
- "description": "Set if key is enabled or disabled. If disabled, the key cannot be used to verify.",
- "example": true
- },
- "roles": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "minLength": 3,
- "description": "The id of the role. Provide either `id` or `name`. If both are provided `id` is used."
- },
- "name": {
- "type": "string",
- "minLength": 1,
- "description": "Identify the role via its name. Provide either `id` or `name`. If both are provided `id` is used."
- },
- "create": {
- "type": "boolean",
- "description": "Set to true to automatically create the permissions they do not exist yet. Only works when specifying `name`.\n Autocreating roles requires your root key to have the `rbac.*.create_role` permission, otherwise the request will get rejected"
- }
- }
- },
- "minItems": 1,
- "description": "The roles you want to set for this key. This overwrites all existing roles.\n Setting roles requires the `rbac.*.add_role_to_key` permission.",
- "example": [
- {
- "id": "perm_123"
- },
- {
- "name": "dns.record.create"
- },
- {
- "name": "dns.record.delete",
- "create": true
- }
- ]
- },
- "permissions": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "minLength": 3,
- "description": "The id of the permission. Provide either `id` or `name`. If both are provided `id` is used."
- },
- "name": {
- "type": "string",
- "minLength": 1,
- "description": "Identify the permission via its name. Provide either `id` or `name`. If both are provided `id` is used."
- },
- "create": {
- "type": "boolean",
- "description": "Set to true to automatically create the permissions they do not exist yet. Only works when specifying `name`.\n Autocreating permissions requires your root key to have the `rbac.*.create_permission` permission, otherwise the request will get rejected"
- }
- }
- },
- "minItems": 1,
- "description": "The permissions you want to set for this key. This overwrites all existing permissions.\n Setting permissions requires the `rbac.*.add_permission_to_key` permission.",
- "example": [
- {
- "id": "perm_123"
- },
- {
- "name": "dns.record.create"
- },
- {
- "name": "dns.record.delete",
- "create": true
- }
- ]
- }
- },
- "required": [
- "keyId"
- ],
- "description": "Update a key's configuration.\n The `apis..update_key` permission is required."
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "The key was successfully updated, it may take up to 30s for this to take effect in all regions",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {}
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/keys.updateRemaining": {
- "post": {
- "tags": [
- "keys"
- ],
- "operationId": "updateRemaining",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "keyId": {
- "type": "string",
- "description": "The id of the key you want to modify",
- "example": "key_123"
- },
- "op": {
- "type": "string",
- "enum": [
- "increment",
- "decrement",
- "set"
- ],
- "description": "The operation you want to perform on the remaining count"
- },
- "value": {
- "type": "integer",
- "nullable": true,
- "description": "The value you want to set, add or subtract the remaining count by",
- "example": 1
- }
- },
- "required": [
- "keyId",
- "op",
- "value"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "The configuration for an api",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "remaining": {
- "type": "integer",
- "nullable": true,
- "description": "The number of remaining requests for this key after updating it. `null` means unlimited.",
- "example": 100
- }
- },
- "required": [
- "remaining"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/keys.getVerifications": {
- "get": {
- "tags": [
- "keys"
- ],
- "operationId": "getVerifications",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "parameters": [
- {
- "schema": {
- "type": "string",
- "description": "The id of the key to fetch, either `keyId` or `ownerId` must be provided",
- "example": "key_1234"
- },
- "required": false,
- "name": "keyId",
- "in": "query"
- },
- {
- "schema": {
- "type": "string",
- "description": "The owner id to fetch keys for, either `keyId` or `ownerId` must be provided",
- "example": "chronark"
- },
- "required": false,
- "name": "ownerId",
- "in": "query"
- },
- {
- "schema": {
- "type": "integer",
- "nullable": true,
- "description": "The start of the period to fetch usage for as unix milliseconds timestamp",
- "example": 1620000000000
- },
- "required": false,
- "name": "start",
- "in": "query"
- },
- {
- "schema": {
- "type": "integer",
- "nullable": true,
- "description": "The end of the period to fetch usage for as unix milliseconds timestamp",
- "example": 1620000000000
- },
- "required": false,
- "name": "end",
- "in": "query"
- },
- {
- "schema": {
- "type": "string",
- "enum": [
- "day"
- ],
- "default": "day",
- "description": "The granularity of the usage data to fetch, currently only `day` is supported",
- "example": "day"
- },
- "required": false,
- "name": "granularity",
- "in": "query"
- }
- ],
- "responses": {
- "200": {
- "description": "Usage numbers over time",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "verifications": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "time": {
- "type": "integer",
- "minimum": 0,
- "exclusiveMinimum": true,
- "description": "The timestamp of the usage data",
- "example": 1620000000000
- },
- "success": {
- "type": "integer",
- "description": "The number of successful requests",
- "example": 100
- },
- "rateLimited": {
- "type": "integer",
- "description": "The number of requests that were rate limited",
- "example": 10
- },
- "usageExceeded": {
- "type": "integer",
- "description": "The number of requests that exceeded the usage limit",
- "example": 0
- }
- },
- "required": [
- "time",
- "success",
- "rateLimited",
- "usageExceeded"
- ]
- }
- }
- },
- "required": [
- "verifications"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/keys.addPermissions": {
- "post": {
- "tags": [
- "keys"
- ],
- "operationId": "addPermissions",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "keyId": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the key."
- },
- "permissions": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "minLength": 3,
- "description": "The id of the permission. Provide either `id` or `name`. If both are provided `id` is used."
- },
- "name": {
- "type": "string",
- "minLength": 1,
- "description": "Identify the permission via its name. Provide either `id` or `name`. If both are provided `id` is used."
- },
- "create": {
- "type": "boolean",
- "description": "Set to true to automatically create the permissions they do not exist yet. Only works when specifying `name`.\n Autocreating permissions requires your root key to have the `rbac.*.create_permission` permission, otherwise the request will get rejected"
- }
- }
- },
- "minItems": 1,
- "description": "The permissions you want to add to this key"
- }
- },
- "required": [
- "keyId",
- "permissions"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "All currently connected permissions",
- "content": {
- "application/json": {
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "description": "The id of the permission. This is used internally",
- "example": "perm_123"
- },
- "name": {
- "type": "string",
- "description": "The name of the permission",
- "example": "dns.record.create"
- }
- },
- "required": [
- "id",
- "name"
- ]
- }
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/keys.removePermissions": {
- "post": {
- "tags": [
- "keys"
- ],
- "operationId": "removePermissions",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "keyId": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the key."
- },
- "permissions": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "minLength": 3,
- "description": "The id of the permission. Provide either `id` or `name`. If both are provided `id` is used."
- },
- "name": {
- "type": "string",
- "minLength": 1,
- "description": "Identify the permission via its name. Provide either `id` or `name`. If both are provided `id` is used."
- }
- }
- },
- "minItems": 1,
- "description": "The permissions you want to remove from this key.",
- "example": [
- {
- "id": "perm_123"
- },
- {
- "name": "dns.record.create"
- }
- ]
- }
- },
- "required": [
- "keyId",
- "permissions"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {}
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/keys.setPermissions": {
- "post": {
- "tags": [
- "keys"
- ],
- "operationId": "setPermissions",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "keyId": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the key."
- },
- "permissions": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "minLength": 3,
- "description": "The id of the permission. Provide either `id` or `name`. If both are provided `id` is used."
- },
- "name": {
- "type": "string",
- "minLength": 1,
- "description": "Identify the permission via its name. Provide either `id` or `name`. If both are provided `id` is used."
- },
- "create": {
- "type": "boolean",
- "description": "Set to true to automatically create the permissions they do not exist yet. Only works when specifying `name`.\n Autocreating permissions requires your root key to have the `rbac.*.create_permission` permission, otherwise the request will get rejected"
- }
- }
- },
- "minItems": 1,
- "description": "The permissions you want to set for this key. This overwrites all existing permissions.\n Setting permissions requires the `rbac.*.add_permission_to_key` permission.",
- "example": [
- {
- "id": "perm_123"
- },
- {
- "name": "dns.record.create"
- },
- {
- "name": "dns.record.delete",
- "create": true
- }
- ]
- }
- },
- "required": [
- "keyId",
- "permissions"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "All currently connected permissions",
- "content": {
- "application/json": {
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "description": "The id of the permission. This is used internally",
- "example": "perm_123"
- },
- "name": {
- "type": "string",
- "description": "The name of the permission",
- "example": "dns.record.create"
- }
- },
- "required": [
- "id",
- "name"
- ]
- }
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/keys.addRoles": {
- "post": {
- "tags": [
- "keys"
- ],
- "operationId": "addRoles",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "keyId": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the key."
- },
- "roles": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "minLength": 3,
- "description": "The id of the role. Provide either `id` or `name`. If both are provided `id` is used."
- },
- "name": {
- "type": "string",
- "minLength": 1,
- "description": "Identify the role via its name. Provide either `id` or `name`. If both are provided `id` is used."
- },
- "create": {
- "type": "boolean",
- "description": "Set to true to automatically create the permissions they do not exist yet. Only works when specifying `name`.\n Autocreating roles requires your root key to have the `rbac.*.create_role` permission, otherwise the request will get rejected"
- }
- }
- },
- "minItems": 1,
- "description": "The roles you want to set for this key. This overwrites all existing roles.\n Setting roles requires the `rbac.*.add_role_to_key` permission.",
- "example": [
- {
- "id": "role_123"
- },
- {
- "name": "dns.record.create"
- },
- {
- "name": "dns.record.delete",
- "create": true
- }
- ]
- }
- },
- "required": [
- "keyId",
- "roles"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "All currently connected roles",
- "content": {
- "application/json": {
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "description": "The id of the role. This is used internally",
- "example": "role_123"
- },
- "name": {
- "type": "string",
- "description": "The name of the role",
- "example": "dns.record.create"
- }
- },
- "required": [
- "id",
- "name"
- ]
- }
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/keys.removeRoles": {
- "post": {
- "tags": [
- "keys"
- ],
- "operationId": "removeRoles",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "keyId": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the key."
- },
- "roles": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "minLength": 3,
- "description": "The id of the role. Provide either `id` or `name`. If both are provided `id` is used."
- },
- "name": {
- "type": "string",
- "minLength": 1,
- "description": "Identify the role via its name. Provide either `id` or `name`. If both are provided `id` is used."
- }
- }
- },
- "minItems": 1,
- "description": "The roles you want to remove from this key.",
- "example": [
- {
- "id": "role_123"
- },
- {
- "name": "dns.record.create"
- }
- ]
- }
- },
- "required": [
- "keyId",
- "roles"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "Success",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {}
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/keys.setRoles": {
- "post": {
- "tags": [
- "keys"
- ],
- "operationId": "setRoles",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "keyId": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the key."
- },
- "roles": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "minLength": 3,
- "description": "The id of the role. Provide either `id` or `name`. If both are provided `id` is used."
- },
- "name": {
- "type": "string",
- "minLength": 1,
- "description": "Identify the role via its name. Provide either `id` or `name`. If both are provided `id` is used."
- },
- "create": {
- "type": "boolean",
- "description": "Set to true to automatically create the permissions they do not exist yet. Only works when specifying `name`.\n Autocreating roles requires your root key to have the `rbac.*.create_role` permission, otherwise the request will get rejected"
- }
- }
- },
- "minItems": 1,
- "description": "The roles you want to set for this key. This overwrites all existing roles.\n Setting roles requires the `rbac.*.add_role_to_key` permission.",
- "example": [
- {
- "id": "role_123"
- },
- {
- "name": "dns.record.create"
- },
- {
- "name": "dns.record.delete",
- "create": true
- }
- ]
- }
- },
- "required": [
- "keyId",
- "roles"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "All currently connected roles",
- "content": {
- "application/json": {
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "description": "The id of the role. This is used internally",
- "example": "role_123"
- },
- "name": {
- "type": "string",
- "description": "The name of the role",
- "example": "dns.record.create"
- }
- },
- "required": [
- "id",
- "name"
- ]
- }
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/apis.getApi": {
- "get": {
- "tags": [
- "apis"
- ],
- "operationId": "getApi",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "parameters": [
- {
- "schema": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the api to fetch",
- "example": "api_1234"
- },
- "required": true,
- "name": "apiId",
- "in": "query"
- }
- ],
- "responses": {
- "200": {
- "description": "The configuration for an api",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "description": "The id of the key",
- "example": "key_1234"
- },
- "workspaceId": {
- "type": "string",
- "description": "The id of the workspace that owns the api",
- "example": "ws_1234"
- },
- "name": {
- "type": "string",
- "description": "The name of the api. This is internal and your users will not see this.",
- "example": "Unkey - Production"
- }
- },
- "required": [
- "id",
- "workspaceId"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/apis.createApi": {
- "post": {
- "tags": [
- "apis"
- ],
- "operationId": "createApi",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "minLength": 3,
- "description": "The name for your API. This is not customer facing.",
- "example": "my-api"
- }
- },
- "required": [
- "name"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "The configuration for an api",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "apiId": {
- "type": "string",
- "description": "The id of the api",
- "example": "api_134"
- }
- },
- "required": [
- "apiId"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/apis.listKeys": {
- "get": {
- "tags": [
- "apis"
- ],
- "operationId": "listKeys",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "parameters": [
- {
- "schema": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the api to fetch",
- "example": "api_1234"
- },
- "required": true,
- "name": "apiId",
- "in": "query"
- },
- {
- "schema": {
- "type": "integer",
- "minimum": 1,
- "maximum": 100,
- "default": 100,
- "description": "The maximum number of keys to return",
- "example": 100
- },
- "required": false,
- "name": "limit",
- "in": "query"
- },
- {
- "schema": {
- "type": "string",
- "description": "Use this to fetch the next page of results. A new cursor will be returned in the response if there are more results."
- },
- "required": false,
- "name": "cursor",
- "in": "query"
- },
- {
- "schema": {
- "type": "string",
- "minLength": 1,
- "description": "Deprecated. Use `externalId` instead.",
- "deprecated": true
- },
- "required": false,
- "name": "ownerId",
- "in": "query"
- },
- {
- "schema": {
- "type": "string",
- "minLength": 1,
- "description": "If provided, this will only return keys where the `externalId` matches."
- },
- "required": false,
- "name": "externalId",
- "in": "query"
- },
- {
- "schema": {
- "type": "boolean",
- "nullable": true,
- "description": "Decrypt and display the raw key. Only possible if the key was encrypted when generated."
- },
- "required": false,
- "name": "decrypt",
- "in": "query"
- }
- ],
- "responses": {
- "200": {
- "description": "The configuration for an api",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "keys": {
- "type": "array",
- "items": {
- "$ref": "#/components/schemas/Key"
- }
- },
- "cursor": {
- "type": "string",
- "description": "The cursor to use for the next page of results, if no cursor is returned, there are no more results",
- "example": "eyJrZXkiOiJrZXlfMTIzNCJ9"
- },
- "total": {
- "type": "integer",
- "description": "The total number of keys for this api"
- }
- },
- "required": [
- "keys",
- "total"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/apis.deleteApi": {
- "post": {
- "tags": [
- "apis"
- ],
- "operationId": "deleteApi",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "apiId": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the api to delete",
- "example": "api_1234"
- }
- },
- "required": [
- "apiId"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "The api was successfully deleted, it may take up to 30s for this to take effect in all regions",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {}
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/apis.deleteKeys": {
- "post": {
- "tags": [
- "apis"
- ],
- "operationId": "deleteKeys",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "apiId": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the api, that the keys belong to.",
- "example": "api_1234"
- },
- "permanent": {
- "type": "boolean",
- "default": false,
- "description": "Delete the keys permanently, if false the keys will be marked as deleted but not removed from the database. In either case, the keys will no longer be valid when verifying them."
- }
- },
- "required": [
- "apiId"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "The keys have been deleted",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "deletedKeys": {
- "type": "integer",
- "description": "The number of keys that were deleted"
- }
- },
- "required": [
- "deletedKeys"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/ratelimits.limit": {
- "post": {
- "tags": [
- "ratelimits"
- ],
- "operationId": "limit",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "namespace": {
- "type": "string",
- "default": "default",
- "description": "Namespaces group different limits together for better analytics. You might have a namespace for your public API and one for internal tRPC routes.",
- "example": "email.outbound"
- },
- "identifier": {
- "type": "string",
- "description": "Identifier of your user, this can be their userId, an email, an ip or anything else.",
- "example": "user_123"
- },
- "limit": {
- "type": "integer",
- "minimum": 0,
- "exclusiveMinimum": true,
- "description": "How many requests may pass in a given window.",
- "example": 10
- },
- "duration": {
- "type": "integer",
- "minimum": 1000,
- "description": "The window duration in milliseconds",
- "example": 60000
- },
- "cost": {
- "type": "integer",
- "minimum": 0,
- "default": 1,
- "description": "Expensive requests may use up more tokens. You can specify a cost to the request here and we'll deduct this many tokens in the current window. \nIf there are not enough tokens left, the request is denied.\n \nSet it to 0 to receive the current limit without changing anything.",
- "example": 2
- },
- "async": {
- "type": "boolean",
- "default": false,
- "description": "Async will return a response immediately, lowering latency at the cost of accuracy."
- },
- "meta": {
- "type": "object",
- "additionalProperties": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "boolean"
- },
- {
- "type": "number"
- },
- {
- "nullable": true
- },
- {
- "nullable": true
- }
- ]
- },
- "description": "Attach any metadata to this request"
- },
- "resources": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "type": {
- "type": "string",
- "description": "The type of resource",
- "example": "organization"
- },
- "id": {
- "type": "string",
- "description": "The unique identifier for the resource",
- "example": "org_123"
- },
- "name": {
- "type": "string",
- "description": "A human readable name for this resource",
- "example": "unkey"
- },
- "meta": {
- "type": "object",
- "additionalProperties": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "boolean"
- },
- {
- "type": "number"
- },
- {
- "nullable": true
- },
- {
- "nullable": true
- }
- ]
- },
- "description": "Attach any metadata to this resources"
- }
- },
- "required": [
- "type",
- "id"
- ]
- },
- "description": "Resources that are about to be accessed by the user",
- "example": [
- {
- "type": "project",
- "id": "p_123",
- "name": "dub"
- }
- ]
- }
- },
- "required": [
- "identifier",
- "limit",
- "duration"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "success": {
- "type": "boolean",
- "description": "Returns true if the request should be processed, false if it was rejected.",
- "example": true
- },
- "limit": {
- "type": "integer",
- "description": "How many requests are allowed within a window.",
- "example": 10
- },
- "remaining": {
- "type": "integer",
- "description": "How many requests can still be made in the current window.",
- "example": 9
- },
- "reset": {
- "type": "integer",
- "description": "A unix millisecond timestamp when the limits reset.",
- "example": 1709804263654
- }
- },
- "required": [
- "success",
- "limit",
- "remaining",
- "reset"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/migrations.createKeys": {
- "post": {
- "tags": [
- "migrations"
- ],
- "operationId": "v1.migrations.createKeys",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "apiId": {
- "type": "string",
- "description": "Choose an `API` where this key should be created.",
- "example": "api_123"
- },
- "prefix": {
- "type": "string",
- "maxLength": 8,
- "description": "To make it easier for your users to understand which product an api key belongs to, you can add prefix them.\n\nFor example Stripe famously prefixes their customer ids with cus_ or their api keys with sk_live_.\n\nThe underscore is automatically added if you are defining a prefix, for example: \"prefix\": \"abc\" will result in a key like abc_xxxxxxxxx\n"
- },
- "name": {
- "type": "string",
- "description": "The name for your Key. This is not customer facing.",
- "example": "my key"
- },
- "plaintext": {
- "type": "string",
- "description": "The raw key in plaintext. If provided, unkey encrypts this value and stores it securely. Provide either `hash` or `plaintext`"
- },
- "hash": {
- "type": "object",
- "properties": {
- "value": {
- "type": "string",
- "description": "The hashed and encoded key"
- },
- "variant": {
- "type": "string",
- "enum": [
- "sha256_base64"
- ],
- "description": "The algorithm for hashing and encoding, currently only sha256 and base64 are supported"
- }
- },
- "required": [
- "value",
- "variant"
- ],
- "description": "Provide either `hash` or `plaintext`"
- },
- "start": {
- "type": "string",
- "description": "The first 4 characters of the key. If a prefix is used, it should be the prefix plus 4 characters.",
- "example": "unkey_32kq"
- },
- "ownerId": {
- "type": "string",
- "description": "Your user’s Id. This will provide a link between Unkey and your customer record.\nWhen validating a key, we will return this back to you, so you can clearly identify your user from their api key.",
- "example": "team_123"
- },
- "meta": {
- "type": "object",
- "additionalProperties": {
- "nullable": true
- },
- "description": "This is a place for dynamic meta data, anything that feels useful for you should go here",
- "example": {
- "billingTier": "PRO",
- "trialEnds": "2023-06-16T17:16:37.161Z"
- }
- },
- "roles": {
- "type": "array",
- "items": {
- "type": "string",
- "minLength": 1,
- "maxLength": 512
- },
- "description": "A list of roles that this key should have. If the role does not exist, an error is thrown",
- "example": [
- "admin",
- "finance"
- ]
- },
- "permissions": {
- "type": "array",
- "items": {
- "type": "string",
- "minLength": 1,
- "maxLength": 512
- },
- "description": "A list of permissions that this key should have. If the permission does not exist, an error is thrown",
- "example": [
- "domains.create_record",
- "say_hello"
- ]
- },
- "expires": {
- "type": "integer",
- "description": "You can auto expire keys by providing a unix timestamp in milliseconds. Once Keys expire they will automatically be disabled and are no longer valid unless you enable them again.",
- "example": 1623869797161
- },
- "remaining": {
- "type": "integer",
- "minimum": 1,
- "description": "You can limit the number of requests a key can make. Once a key reaches 0 remaining requests, it will automatically be disabled and is no longer valid unless you update it.",
- "example": 1000,
- "externalDocs": {
- "description": "Learn more",
- "url": "https://unkey.dev/docs/features/remaining"
- }
- },
- "refill": {
- "type": "object",
- "properties": {
- "interval": {
- "type": "string",
- "enum": [
- "daily",
- "monthly"
- ],
- "description": "Unkey will automatically refill verifications at the set interval."
- },
- "amount": {
- "type": "integer",
- "minimum": 0,
- "exclusiveMinimum": true,
- "description": "The number of verifications to refill for each occurrence is determined individually for each key."
- }
- },
- "required": [
- "interval",
- "amount"
- ],
- "description": "Unkey enables you to refill verifications for each key at regular intervals.",
- "example": {
- "interval": "daily",
- "amount": 100
- }
- },
- "ratelimit": {
- "type": "object",
- "properties": {
- "async": {
- "type": "boolean",
- "default": false,
- "description": "Async will return a response immediately, lowering latency at the cost of accuracy.",
- "externalDocs": {
- "description": "Learn more",
- "url": "https://unkey.dev/docs/features/ratelimiting"
- }
- },
- "type": {
- "type": "string",
- "enum": [
- "fast",
- "consistent"
- ],
- "default": "fast",
- "description": "Fast ratelimiting doesn't add latency, while consistent ratelimiting is more accurate.",
- "deprecated": true,
- "externalDocs": {
- "description": "Learn more",
- "url": "https://unkey.dev/docs/features/ratelimiting"
- }
- },
- "limit": {
- "type": "integer",
- "minimum": 1,
- "description": "The total amount of burstable requests."
- },
- "refillRate": {
- "type": "integer",
- "minimum": 1,
- "description": "How many tokens to refill during each refillInterval.",
- "deprecated": true
- },
- "refillInterval": {
- "type": "integer",
- "minimum": 1,
- "description": "Determines the speed at which tokens are refilled, in milliseconds.",
- "deprecated": true
- }
- },
- "required": [
- "limit",
- "refillRate",
- "refillInterval"
- ],
- "description": "Unkey comes with per-key ratelimiting out of the box.",
- "example": {
- "type": "fast",
- "limit": 10,
- "refillRate": 1,
- "refillInterval": 60
- }
- },
- "enabled": {
- "type": "boolean",
- "default": true,
- "description": "Sets if key is enabled or disabled. Disabled keys are not valid.",
- "example": false
- },
- "environment": {
- "type": "string",
- "maxLength": 256,
- "description": "Environments allow you to divide your keyspace.\n\nSome applications like Stripe, Clerk, WorkOS and others have a concept of \"live\" and \"test\" keys to\ngive the developer a way to develop their own application without the risk of modifying real world\nresources.\n\nWhen you set an environment, we will return it back to you when validating the key, so you can\nhandle it correctly.\n "
- }
- },
- "required": [
- "apiId"
- ]
- },
- "maxItems": 100
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "The key ids of all created keys",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "keyIds": {
- "type": "array",
- "items": {
- "type": "string"
- },
- "description": "The ids of the keys. This is not a secret and can be stored as a reference if you wish. You need the keyId to update or delete a key later.",
- "example": [
- "key_123",
- "key_456"
- ]
- }
- },
- "required": [
- "keyIds"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/migrations.enqueueKeys": {
- "post": {
- "tags": [
- "migrations"
- ],
- "operationId": "v1.migrations.enqueueKeys",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "migrationId": {
- "type": "string",
- "description": "Contact support@unkey.dev to receive your migration id."
- },
- "apiId": {
- "type": "string",
- "description": "The id of the api, you want to migrate keys to"
- },
- "keys": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "prefix": {
- "type": "string",
- "maxLength": 8,
- "description": "To make it easier for your users to understand which product an api key belongs to, you can add prefix them.\n\nFor example Stripe famously prefixes their customer ids with cus_ or their api keys with sk_live_.\n\nThe underscore is automatically added if you are defining a prefix, for example: \"prefix\": \"abc\" will result in a key like abc_xxxxxxxxx\n"
- },
- "name": {
- "type": "string",
- "description": "The name for your Key. This is not customer facing.",
- "example": "my key"
- },
- "plaintext": {
- "type": "string",
- "description": "The raw key in plaintext. If provided, unkey encrypts this value and stores it securely. Provide either `hash` or `plaintext`"
- },
- "hash": {
- "type": "object",
- "properties": {
- "value": {
- "type": "string",
- "description": "The hashed and encoded key"
- },
- "variant": {
- "type": "string",
- "enum": [
- "sha256_base64"
- ],
- "description": "The algorithm for hashing and encoding, currently only sha256 and base64 are supported"
- }
- },
- "required": [
- "value",
- "variant"
- ],
- "description": "Provide either `hash` or `plaintext`"
- },
- "start": {
- "type": "string",
- "description": "The first 4 characters of the key. If a prefix is used, it should be the prefix plus 4 characters.",
- "example": "unkey_32kq"
- },
- "ownerId": {
- "type": "string",
- "description": "Your user’s Id. This will provide a link between Unkey and your customer record.\nWhen validating a key, we will return this back to you, so you can clearly identify your user from their api key.",
- "example": "team_123"
- },
- "meta": {
- "type": "object",
- "additionalProperties": {
- "nullable": true
- },
- "description": "This is a place for dynamic meta data, anything that feels useful for you should go here",
- "example": {
- "billingTier": "PRO",
- "trialEnds": "2023-06-16T17:16:37.161Z"
- }
- },
- "roles": {
- "type": "array",
- "items": {
- "type": "string",
- "minLength": 1,
- "maxLength": 512
- },
- "description": "A list of roles that this key should have. If the role does not exist, an error is thrown",
- "example": [
- "admin",
- "finance"
- ]
- },
- "permissions": {
- "type": "array",
- "items": {
- "type": "string",
- "minLength": 1,
- "maxLength": 512
- },
- "description": "A list of permissions that this key should have. If the permission does not exist, an error is thrown",
- "example": [
- "domains.create_record",
- "say_hello"
- ]
- },
- "expires": {
- "type": "integer",
- "description": "You can auto expire keys by providing a unix timestamp in milliseconds. Once Keys expire they will automatically be disabled and are no longer valid unless you enable them again.",
- "example": 1623869797161
- },
- "remaining": {
- "type": "integer",
- "minimum": 1,
- "description": "You can limit the number of requests a key can make. Once a key reaches 0 remaining requests, it will automatically be disabled and is no longer valid unless you update it.",
- "example": 1000,
- "externalDocs": {
- "description": "Learn more",
- "url": "https://unkey.dev/docs/features/remaining"
- }
- },
- "refill": {
- "type": "object",
- "properties": {
- "interval": {
- "type": "string",
- "enum": [
- "daily",
- "monthly"
- ],
- "description": "Unkey will automatically refill verifications at the set interval."
- },
- "amount": {
- "type": "integer",
- "minimum": 0,
- "exclusiveMinimum": true,
- "description": "The number of verifications to refill for each occurrence is determined individually for each key."
- }
- },
- "required": [
- "interval",
- "amount"
- ],
- "description": "Unkey enables you to refill verifications for each key at regular intervals.",
- "example": {
- "interval": "daily",
- "amount": 100
- }
- },
- "ratelimit": {
- "type": "object",
- "properties": {
- "async": {
- "type": "boolean",
- "default": true,
- "description": "Async will return a response immediately, lowering latency at the cost of accuracy.",
- "externalDocs": {
- "description": "Learn more",
- "url": "https://unkey.dev/docs/features/ratelimiting"
- }
- },
- "type": {
- "type": "string",
- "enum": [
- "fast",
- "consistent"
- ],
- "default": "fast",
- "description": "Deprecated, use `async`. Fast ratelimiting doesn't add latency, while consistent ratelimiting is more accurate.",
- "externalDocs": {
- "description": "Learn more",
- "url": "https://unkey.dev/docs/features/ratelimiting"
- },
- "deprecated": true
- },
- "limit": {
- "type": "integer",
- "minimum": 1,
- "description": "The total amount of requests in a given interval."
- },
- "duration": {
- "type": "integer",
- "minimum": 1000,
- "description": "The window duration in milliseconds",
- "example": 60000
- },
- "refillRate": {
- "type": "integer",
- "minimum": 1,
- "description": "How many tokens to refill during each refillInterval.",
- "deprecated": true
- },
- "refillInterval": {
- "type": "integer",
- "minimum": 1,
- "description": "The refill timeframe, in milliseconds.",
- "deprecated": true
- }
- },
- "required": [
- "limit",
- "duration"
- ],
- "description": "Unkey comes with per-key fixed-window ratelimiting out of the box.",
- "example": {
- "type": "fast",
- "limit": 10,
- "duration": 60000
- }
- },
- "enabled": {
- "type": "boolean",
- "default": true,
- "description": "Sets if key is enabled or disabled. Disabled keys are not valid.",
- "example": false
- },
- "environment": {
- "type": "string",
- "maxLength": 256,
- "description": "Environments allow you to divide your keyspace.\n\nSome applications like Stripe, Clerk, WorkOS and others have a concept of \"live\" and \"test\" keys to\ngive the developer a way to develop their own application without the risk of modifying real world\nresources.\n\nWhen you set an environment, we will return it back to you when validating the key, so you can\nhandle it correctly.\n "
- }
- }
- },
- "maxItems": 100
- }
- },
- "required": [
- "migrationId",
- "apiId",
- "keys"
- ]
- }
- }
- }
- },
- "responses": {
- "202": {
- "description": "The key ids of all created keys",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {}
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/permissions.createPermission": {
- "post": {
- "tags": [
- "permissions"
- ],
- "operationId": "createPermission",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "minLength": 3,
- "pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
- "description": "The unique name of your permission.",
- "example": "record.write"
- },
- "description": {
- "type": "string",
- "description": "Explain what this permission does. This is just for your team, your users will not see this.",
- "example": "record.write can create new dns records for our domains."
- }
- },
- "required": [
- "name"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "Sucessfully created a permission",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "permissionId": {
- "type": "string",
- "description": "The id of the permission. This is used internally",
- "example": "perm_123"
- }
- },
- "required": [
- "permissionId"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/permissions.deletePermission": {
- "post": {
- "tags": [
- "permissions"
- ],
- "operationId": "deletePermission",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "permissionId": {
- "type": "string",
- "description": "The id of the permission you want to delete.",
- "example": "perm_123"
- }
- },
- "required": [
- "permissionId"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "Sucessfully deleted a permission",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {}
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/permissions.getPermission": {
- "get": {
- "tags": [
- "permissions"
- ],
- "operationId": "getPermission",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "parameters": [
- {
- "schema": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the permission to fetch",
- "example": "perm_123"
- },
- "required": true,
- "name": "permissionId",
- "in": "query"
- }
- ],
- "responses": {
- "200": {
- "description": "The Role",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "description": "The id of the permission",
- "example": "perm_123"
- },
- "name": {
- "type": "string",
- "description": "The name of the permission.",
- "example": "domain.record.manager"
- },
- "description": {
- "type": "string",
- "description": "The description of what this permission does. This is just for your team, your users will not see this.",
- "example": "Can manage dns records"
- }
- },
- "required": [
- "id",
- "name"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/permissions.listPermissions": {
- "get": {
- "tags": [
- "permissions"
- ],
- "operationId": "listPermissions",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "responses": {
- "200": {
- "description": "The permissions in your workspace",
- "content": {
- "application/json": {
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "description": "The id of the permission",
- "example": "perm_123"
- },
- "name": {
- "type": "string",
- "description": "The name of the permission.",
- "example": "domain.record.manager"
- },
- "description": {
- "type": "string",
- "description": "The description of what this permission does. This is just for your team, your users will not see this.",
- "example": "Can manage dns records"
- }
- },
- "required": [
- "id",
- "name"
- ]
- }
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/permissions.createRole": {
- "post": {
- "tags": [
- "permissions"
- ],
- "operationId": "createRole",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "minLength": 3,
- "pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
- "description": "The unique name of your role.",
- "example": "dns.records.manager"
- },
- "description": {
- "type": "string",
- "description": "Explain what this role does. This is just for your team, your users will not see this.",
- "example": "dns.records.manager can read and write dns records for our domains."
- }
- },
- "required": [
- "name"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "Sucessfully created a role",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "roleId": {
- "type": "string",
- "description": "The id of the role. This is used internally",
- "example": "role_123"
- }
- },
- "required": [
- "roleId"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/permissions.deleteRole": {
- "post": {
- "tags": [
- "permissions"
- ],
- "operationId": "deleteRole",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "roleId": {
- "type": "string",
- "description": "The id of the role you want to delete.",
- "example": "role_123"
- }
- },
- "required": [
- "roleId"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "Sucessfully deleted a role",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {}
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/permissions.getRole": {
- "get": {
- "tags": [
- "permissions"
- ],
- "operationId": "getRole",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "parameters": [
- {
- "schema": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the role to fetch",
- "example": "role_123"
- },
- "required": true,
- "name": "roleId",
- "in": "query"
- }
- ],
- "responses": {
- "200": {
- "description": "The Role",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "description": "The id of the role",
- "example": "role_1234"
- },
- "name": {
- "type": "string",
- "description": "The name of the role.",
- "example": "domain.record.manager"
- },
- "description": {
- "type": "string",
- "description": "The description of what this role does. This is just for your team, your users will not see this.",
- "example": "Can manage dns records"
- }
- },
- "required": [
- "id",
- "name"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/permissions.listRoles": {
- "get": {
- "tags": [
- "permissions"
- ],
- "operationId": "listRoles",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "responses": {
- "200": {
- "description": "The Roles in your workspace",
- "content": {
- "application/json": {
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "description": "The id of the role",
- "example": "role_1234"
- },
- "name": {
- "type": "string",
- "description": "The name of the role.",
- "example": "domain.record.manager"
- },
- "description": {
- "type": "string",
- "description": "The description of what this role does. This is just for your team, your users will not see this.",
- "example": "Can manage dns records"
- }
- },
- "required": [
- "id",
- "name"
- ]
- }
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/identities.createIdentity": {
- "post": {
- "tags": [
- "identities"
- ],
- "operationId": "createIdentity",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "externalId": {
- "type": "string",
- "minLength": 3,
- "description": "The id of this identity in your system.\n\nThis usually comes from your authentication provider and could be a userId, organisationId or even an email.\nIt does not matter what you use, as long as it uniquely identifies something in your application.\n ",
- "example": "user_123"
- },
- "meta": {
- "type": "object",
- "additionalProperties": {
- "nullable": true
- },
- "description": "Attach metadata to this identity that you need to have access to when verifying a key.\n\nThis will be returned as part of the `verifyKey` response.\n"
- },
- "ratelimits": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "The name of this limit. You will need to use this again when verifying a key.",
- "example": "tokens"
- },
- "limit": {
- "type": "integer",
- "minimum": 1,
- "description": "How many requests may pass within a given window before requests are rejected.",
- "example": 10
- },
- "duration": {
- "type": "integer",
- "minimum": 1000,
- "description": "The duration for each ratelimit window in milliseconds.",
- "example": 1000
- }
- },
- "required": [
- "name",
- "limit",
- "duration"
- ]
- },
- "description": "Attach ratelimits to this identity.\n\nWhen verifying keys, you can specify which limits you want to use and all keys attached to this identity, will share the limits."
- }
- },
- "required": [
- "externalId"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "The configuration for an api",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "identityId": {
- "type": "string",
- "description": "The id of the identity. Used internally, you do not need to store this.",
- "example": "id_123"
- }
- },
- "required": [
- "identityId"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/identities.getIdentity": {
- "get": {
- "tags": [
- "identities"
- ],
- "operationId": "getIdentity",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "parameters": [
- {
- "schema": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the identity to fetch, use either `identityId` or `externalId`, if both are provided, `identityId` takes precedence.",
- "example": "id_1234"
- },
- "required": false,
- "name": "identityId",
- "in": "query"
- },
- {
- "schema": {
- "type": "string",
- "minLength": 1,
- "description": "The externalId of the identity to fetch, use either `identityId` or `externalId`, if both are provided, `identityId` takes precedence.",
- "example": "id_1234"
- },
- "required": false,
- "name": "externalId",
- "in": "query"
- }
- ],
- "responses": {
- "200": {
- "description": "The configuration for an api",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "description": "The id of this identity. Used to interact with unkey's API"
- },
- "externalId": {
- "type": "string",
- "description": "The id in your system"
- },
- "meta": {
- "type": "object",
- "additionalProperties": {
- "nullable": true
- },
- "description": "The meta object defined for this identity."
- },
- "ratelimits": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "The name of this limit. You will need to use this again when verifying a key.",
- "example": "tokens"
- },
- "limit": {
- "type": "integer",
- "minimum": 1,
- "description": "How many requests may pass within a given window before requests are rejected.",
- "example": 10
- },
- "duration": {
- "type": "integer",
- "minimum": 1000,
- "description": "The duration for each ratelimit window in milliseconds.",
- "example": 1000
- }
- },
- "required": [
- "name",
- "limit",
- "duration"
- ]
- },
- "description": "When verifying keys, you can specify which limits you want to use and all keys attached to this identity, will share the limits."
- }
- },
- "required": [
- "id",
- "externalId",
- "meta",
- "ratelimits"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/identities.listIdentities": {
- "get": {
- "tags": [
- "identities"
- ],
- "operationId": "listIdentities",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "x-speakeasy-pagination": {
- "type": "cursor",
- "inputs": [
- {
- "name": "cursor",
- "in": "parameters",
- "type": "cursor"
- }
- ],
- "outputs": {
- "nextCursor": "$.cursor"
- }
- },
- "parameters": [
- {
- "schema": {
- "type": "string",
- "default": "default",
- "description": "This is not yet used but here for future compatibility."
- },
- "required": false,
- "name": "environment",
- "in": "query"
- },
- {
- "schema": {
- "type": "integer",
- "minimum": 1,
- "maximum": 100,
- "default": 100,
- "description": "The maximum number of identities to return",
- "example": 100
- },
- "required": false,
- "name": "limit",
- "in": "query"
- },
- {
- "schema": {
- "type": "string",
- "description": "Use this to fetch the next page of results. A new cursor will be returned in the response if there are more results."
- },
- "required": false,
- "name": "cursor",
- "in": "query"
- }
- ],
- "responses": {
- "200": {
- "description": "A list of identities.",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "identities": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "description": "The id of this identity. Used to interact with unkey's API"
- },
- "externalId": {
- "type": "string",
- "description": "The id in your system"
- },
- "ratelimits": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "The name of this limit. You will need to use this again when verifying a key.",
- "example": "tokens"
- },
- "limit": {
- "type": "integer",
- "minimum": 1,
- "description": "How many requests may pass within a given window before requests are rejected.",
- "example": 10
- },
- "duration": {
- "type": "integer",
- "minimum": 1000,
- "description": "The duration for each ratelimit window in milliseconds.",
- "example": 1000
- }
- },
- "required": [
- "name",
- "limit",
- "duration"
- ]
- },
- "description": "When verifying keys, you can specify which limits you want to use and all keys attached to this identity, will share the limits."
- }
- },
- "required": [
- "id",
- "externalId",
- "ratelimits"
- ]
- },
- "description": "A list of identities."
- },
- "cursor": {
- "type": "string",
- "description": "The cursor to use for the next page of results, if no cursor is returned, there are no more results",
- "example": "eyJrZXkiOiJrZXlfMTIzNCJ9"
- },
- "total": {
- "type": "integer",
- "description": "The total number of identities for this environment"
- }
- },
- "required": [
- "identities",
- "total"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/identities.updateIdentity": {
- "post": {
- "tags": [
- "identities"
- ],
- "operationId": "updateIdentity",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "identityId": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the identity to update, use either `identityId` or `externalId`, if both are provided, `identityId` takes precedence.",
- "example": "id_1234"
- },
- "externalId": {
- "type": "string",
- "minLength": 1,
- "description": "The externalId of the identity to update, use either `identityId` or `externalId`, if both are provided, `identityId` takes precedence.",
- "example": "user_1234"
- },
- "environment": {
- "type": "string",
- "default": "default",
- "description": "This is not yet used but here for future compatibility."
- },
- "meta": {
- "type": "object",
- "additionalProperties": {
- "nullable": true
- },
- "description": "Attach metadata to this identity that you need to have access to when verifying a key.\n\nSet to `{}` to clear.\n\nThis will be returned as part of the `verifyKey` response.\n"
- },
- "ratelimits": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "The name of this limit. You will need to use this again when verifying a key.",
- "example": "tokens"
- },
- "limit": {
- "type": "integer",
- "minimum": 1,
- "description": "How many requests may pass within a given window before requests are rejected.",
- "example": 10
- },
- "duration": {
- "type": "integer",
- "minimum": 1000,
- "description": "The duration for each ratelimit window in milliseconds.",
- "example": 1000
- }
- },
- "required": [
- "name",
- "limit",
- "duration"
- ]
- },
- "description": "Attach ratelimits to this identity.\n\nThis overwrites all existing ratelimits on this identity.\nSetting an empty array will delete all existing ratelimits.\n\nWhen verifying keys, you can specify which limits you want to use and all keys attached to this identity, will share the limits."
- }
- }
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "The identity after the update.",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string",
- "description": "The id of the identity.",
- "example": "id_1234"
- },
- "externalId": {
- "type": "string",
- "description": "The externalId of the identity.",
- "example": "user_1234"
- },
- "meta": {
- "type": "object",
- "additionalProperties": {
- "nullable": true
- },
- "description": "The metadata attached to this identity.",
- "example": {
- "stripeSubscriptionId": "sub_1234"
- }
- },
- "ratelimits": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "The name of this limit.",
- "example": "tokens"
- },
- "limit": {
- "type": "integer",
- "description": "How many requests may pass within a given window before requests are rejected.",
- "example": 10
- },
- "duration": {
- "type": "integer",
- "description": "The duration for each ratelimit window in milliseconds.",
- "example": 1000
- }
- },
- "required": [
- "name",
- "limit",
- "duration"
- ]
- }
- }
- },
- "required": [
- "id",
- "externalId",
- "meta",
- "ratelimits"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/identities.deleteIdentity": {
- "post": {
- "tags": [
- "identities"
- ],
- "operationId": "deleteIdentity",
- "security": [
- {
- "bearerAuth": []
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "identityId": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the identity to delete",
- "example": "id_1234"
- }
- },
- "required": [
- "identityId"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "The identity was successfully deleted, it may take up to 30s for this to take effect in all regions",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {}
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/keys": {
- "post": {
- "operationId": "deprecated.createKey",
- "x-speakeasy-ignore": true,
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "apiId": {
- "type": "string",
- "description": "Choose an `API` where this key should be created.",
- "example": "api_123"
- },
- "prefix": {
- "type": "string",
- "maxLength": 8,
- "description": "To make it easier for your users to understand which product an api key belongs to, you can add prefix them.\n\nFor example Stripe famously prefixes their customer ids with cus_ or their api keys with sk_live_.\n\nThe underscore is automatically added if you are defining a prefix, for example: \"prefix\": \"abc\" will result in a key like abc_xxxxxxxxx\n"
- },
- "name": {
- "type": "string",
- "description": "The name for your Key. This is not customer facing.",
- "example": "my key"
- },
- "byteLength": {
- "type": "integer",
- "minimum": 16,
- "maximum": 255,
- "default": 16,
- "description": "The byte length used to generate your key determines its entropy as well as its length. Higher is better, but keys become longer and more annoying to handle. The default is 16 bytes, or 2^^128 possible combinations."
- },
- "ownerId": {
- "type": "string",
- "description": "Your user’s Id. This will provide a link between Unkey and your customer record.\nWhen validating a key, we will return this back to you, so you can clearly identify your user from their api key.",
- "example": "team_123"
- },
- "meta": {
- "type": "object",
- "additionalProperties": {
- "nullable": true
- },
- "description": "This is a place for dynamic meta data, anything that feels useful for you should go here",
- "example": {
- "billingTier": "PRO",
- "trialEnds": "2023-06-16T17:16:37.161Z"
- }
- },
- "expires": {
- "type": "integer",
- "description": "You can auto expire keys by providing a unix timestamp in milliseconds. Once Keys expire they will automatically be disabled and are no longer valid unless you enable them again.",
- "example": 1623869797161
- },
- "remaining": {
- "type": "integer",
- "description": "You can limit the number of requests a key can make. Once a key reaches 0 remaining requests, it will automatically be disabled and is no longer valid unless you update it.",
- "example": 1000,
- "externalDocs": {
- "description": "Learn more",
- "url": "https://unkey.dev/docs/features/remaining"
- }
- },
- "ratelimit": {
- "type": "object",
- "properties": {
- "type": {
- "type": "string",
- "enum": [
- "fast",
- "consistent"
- ],
- "default": "fast",
- "description": "Fast ratelimiting doesn't add latency, while consistent ratelimiting is more accurate.",
- "externalDocs": {
- "description": "Learn more",
- "url": "https://unkey.dev/docs/features/ratelimiting"
- }
- },
- "limit": {
- "type": "integer",
- "minimum": 1,
- "description": "The total amount of burstable requests."
- },
- "refillRate": {
- "type": "integer",
- "minimum": 1,
- "description": "How many tokens to refill during each refillInterval."
- },
- "refillInterval": {
- "type": "integer",
- "minimum": 1,
- "description": "Determines the speed at which tokens are refilled, in milliseconds."
- }
- },
- "required": [
- "limit",
- "refillRate",
- "refillInterval"
- ],
- "description": "Unkey comes with per-key ratelimiting out of the box.",
- "example": {
- "type": "fast",
- "limit": 10,
- "refillRate": 1,
- "refillInterval": 60
- }
- }
- },
- "required": [
- "apiId"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "The configuration for an api",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "keyId": {
- "type": "string",
- "description": "The id of the key. This is not a secret and can be stored as a reference if you wish. You need the keyId to update or delete a key later.",
- "example": "key_123"
- },
- "key": {
- "type": "string",
- "description": "The newly created api key, do not store this on your own system but pass it along to your user.",
- "example": "prefix_xxxxxxxxx"
- }
- },
- "required": [
- "keyId",
- "key"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/keys/verify": {
- "post": {
- "deprecated": true,
- "operationId": "deprecated.verifyKey",
- "x-speakeasy-ignore": true,
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "apiId": {
- "type": "string",
- "description": "The id of the api where the key belongs to. This is optional for now but will be required soon.\nThe key will be verified against the api's configuration. If the key does not belong to the api, the verification will fail.",
- "example": "api_1234"
- },
- "key": {
- "type": "string",
- "minLength": 1,
- "description": "The key to verify",
- "example": "sk_1234"
- }
- },
- "required": [
- "key"
- ]
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "The verification result",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "keyId": {
- "type": "string",
- "description": "The id of the key",
- "example": "key_1234"
- },
- "valid": {
- "type": "boolean",
- "description": "Whether the key is valid or not.\nA key could be invalid for a number of reasons, for example if it has expired, has no more verifications left or if it has been deleted.",
- "example": true
- },
- "name": {
- "type": "string",
- "description": "The name of the key, give keys a name to easily identifiy their purpose",
- "example": "Customer X"
- },
- "ownerId": {
- "type": "string",
- "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"
- },
- "meta": {
- "type": "object",
- "additionalProperties": {
- "nullable": true
- },
- "description": "Any additional metadata you want to store with the key",
- "example": {
- "roles": [
- "admin",
- "user"
- ],
- "stripeCustomerId": "cus_1234"
- }
- },
- "createdAt": {
- "type": "integer",
- "description": "The unix timestamp in milliseconds when the key was created",
- "example": 0
- },
- "expires": {
- "type": "integer",
- "description": "The unix timestamp in milliseconds when the key will expire. If this field is null or undefined, the key is not expiring.",
- "example": 123
- },
- "ratelimit": {
- "type": "object",
- "properties": {
- "limit": {
- "type": "integer",
- "description": "Maximum number of requests that can be made inside a window",
- "example": 10
- },
- "remaining": {
- "type": "integer",
- "description": "Remaining requests after this verification",
- "example": 9
- },
- "reset": {
- "type": "integer",
- "description": "Unix timestamp in milliseconds when the ratelimit will reset",
- "example": 3600000
- }
- },
- "required": [
- "limit",
- "remaining",
- "reset"
- ],
- "description": "The ratelimit configuration for this key. If this field is null or undefined, the key has no ratelimit.",
- "example": {
- "limit": 10,
- "remaining": 9,
- "reset": 3600000
- }
- },
- "remaining": {
- "type": "integer",
- "description": "The number of requests that can be made with this key before it becomes invalid. If this field is null or undefined, the key has no request limit.",
- "example": 1000
- },
- "code": {
- "type": "string",
- "enum": [
- "NOT_FOUND",
- "FORBIDDEN",
- "USAGE_EXCEEDED",
- "RATE_LIMITED",
- "UNAUTHORIZED",
- "DISABLED",
- "INSUFFICIENT_PERMISSIONS",
- "EXPIRED"
- ],
- "description": "If the key is invalid this field will be set to the reason why it is invalid.\nPossible values are:\n- NOT_FOUND: the key does not exist or has expired\n- FORBIDDEN: the key is not allowed to access the api\n- USAGE_EXCEEDED: the key has exceeded its request limit\n- RATE_LIMITED: the key has been ratelimited,\n- INSUFFICIENT_PERMISSIONS: you do not have the required permissions to perform this action\n",
- "example": "NOT_FOUND"
- }
- },
- "required": [
- "valid"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- },
- "/v1/apis/{apiId}/keys": {
- "get": {
- "operationId": "deprecated.listKeys",
- "x-speakeasy-ignore": true,
- "parameters": [
- {
- "schema": {
- "type": "string",
- "minLength": 1,
- "description": "The id of the api to fetch",
- "example": "api_1234"
- },
- "required": true,
- "name": "apiId",
- "in": "path"
- },
- {
- "schema": {
- "type": "integer",
- "minimum": 1,
- "maximum": 100,
- "default": 100,
- "description": "The maximum number of keys to return",
- "example": 100
- },
- "required": false,
- "name": "limit",
- "in": "query"
- },
- {
- "schema": {
- "type": "number",
- "nullable": true,
- "description": "Use this to fetch the next page of results. A new cursor will be returned in the response if there are more results."
- },
- "required": false,
- "name": "offset",
- "in": "query"
- },
- {
- "schema": {
- "type": "string",
- "minLength": 1,
- "description": "If provided, this will only return keys where the `ownerId` matches."
- },
- "required": false,
- "name": "ownerId",
- "in": "query"
- }
- ],
- "responses": {
- "200": {
- "description": "Keys belonging to the api",
- "content": {
- "application/json": {
- "schema": {
- "type": "object",
- "properties": {
- "keys": {
- "type": "array",
- "items": {
- "$ref": "#/components/schemas/Key"
- }
- },
- "total": {
- "type": "integer",
- "description": "The total number of keys for this api"
- }
- },
- "required": [
- "keys",
- "total"
- ]
- }
- }
- }
- },
- "400": {
- "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).",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrBadRequest"
- }
- }
- }
- },
- "401": {
- "description": "Although the HTTP standard specifies \"unauthorized\", semantically this response means \"unauthenticated\". That is, the client must authenticate itself to get the requested response.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrUnauthorized"
- }
- }
- }
- },
- "403": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrForbidden"
- }
- }
- }
- },
- "404": {
- "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.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrNotFound"
- }
- }
- }
- },
- "409": {
- "description": "This response is sent when a request conflicts with the current state of the server.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrConflict"
- }
- }
- }
- },
- "429": {
- "description": "The user has sent too many requests in a given amount of time (\"rate limiting\")",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrTooManyRequests"
- }
- }
- }
- },
- "500": {
- "description": "The server has encountered a situation it does not know how to handle.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/ErrInternalServerError"
- }
- }
- }
- }
- }
- }
- }
- }
-}
\ No newline at end of file
diff --git a/docs/openapi.yml b/docs/openapi.yml
deleted file mode 100644
index 38d8db3f..00000000
--- a/docs/openapi.yml
+++ /dev/null
@@ -1,1341 +0,0 @@
-openapi: 3.1.1
-info:
- title: Better Auth API
- description: |
- The Better Auth API Endpoints gets documented here.
-
- ## Resources
-
- * https://github.com/better-auth/better-auth
- * https://better-auth.com
- version: 1.0.0
- contact:
- url: https://better-auth.com
-servers:
- - url: '{protocol}://{baseURL}/{path}'
- description: Responds with your request data
- variables:
- baseURL:
- default: 'localhost:3000'
- protocol:
- enum:
- - https
- default: https
- path:
- default: ''
-security:
- - bearerAuth: []
- - apiKeyCookie: []
-tags:
- - name: Sessions
- description: Everything about sessions
- - name: Account
- description: Everything about account
- - name: Callback
- description: Everything about callback
- - name: Email Verification
- description: Everything about email verification
- - name: Forget Password
- description: Everything about forget password
- - name: Sign in
- description: Everything about sign in
- - name: Sign out
- description: Everything about sign out
- - name: Sign up
- description: Everything about sign up
- - name: Update user
- description: Everything about update user
-paths:
- '/get-session':
- get:
- tags:
- - Sessions
- summary: Get current session
- descriptions: It's used to get the currently logged in session.
- operationId: getSession
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- '$ref': '#/components/schemas/Session'
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/responses/Unauthorized'
- '/list-sessions':
- get:
- tags:
- - Sessions
- summary: List all sessions
- descriptions: It's used to list all the sessions.
- operationId: listSessions
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: array
- items:
- '$ref': '#/components/schemas/Session'
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/responses/Unauthorized'
- '/revoke-session':
- post:
- tags:
- - Sessions
- summary: Revoke a session
- descriptions: It's used to revoke a session.
- operationId: revokeSession
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- requestBody:
- description: Session ID
- content:
- application/json:
- schema:
- type: object
- properties:
- id:
- type: string
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- status:
- type: boolean
- examples:
- - true
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/responses/Unauthorized'
- '/revoke-sessions':
- post:
- tags:
- - Sessions
- summary: Revoke all sessions
- descriptions: It's used to revoke all sessions.
- operationId: revokeSessions
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- status:
- type: boolean
- examples:
- - true
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/responses/Unauthorized'
- '/revoke-other-sessions':
- post:
- tags:
- - Sessions
- summary: Revoke other sessions
- descriptions: It's used to revoke all other sessions, other than the current one.
- operationId: revokeOtherSessions
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- status:
- type: boolean
- examples:
- - true
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/responses/Unauthorized'
- '/list-accounts':
- get:
- tags:
- - Account
- summary: List all accounts
- descriptions: It's used to list all the accounts linked to the current user.
- operationId: listAccounts
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: array
- items:
- '$ref': '#/components/schemas/Account'
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/responses/Unauthorized'
- '/link-social':
- post:
- tags:
- - Account
- summary: Link social account
- descriptions: It's used to link social account to the current user.
- operationId: linkSocial
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- currentURL:
- name: currentURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- provider:
- type: string
- examples:
- - google
- - facebook
- - github
- - gitlab
- - twitter
- - linkedin
- - microsoft
- default: google
- callbackURL:
- type: string
- format: url
- required: false
- examples:
- - https://better-auth.com
- default: http://localhost:3000
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- url:
- type: string
- format: url
- redirect:
- type: boolean
- examples:
- - true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Social Account is already linked.
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/responses/Unauthorized'
- '404':
- description: Not Found
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Provider not found
- '/callback/:id':
- get:
- tags:
- - Callback
- summary: Callback
- descriptions: It's used to callback the social account.
- operationId: callback
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- id:
- name: id
- in: path
- required: true
- schema:
- type: string
- state:
- name: state
- in: query
- required: true
- schema:
- type: string
- code:
- name: code
- in: query
- required: false
- schema:
- type: string
- error:
- name: error
- in: query
- required: false
- schema:
- type: string
- responses:
- '302':
- description: Redirect on error or success
- '/send-verification-email':
- post:
- tags:
- - Email Verification
- summary: Send verification email
- descriptions: It's used to send verification email.
- operationId: sendVerificationEmail
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- currentURL:
- name: currentURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- examples:
- - bekacru@better-auth.com
- callbackURL:
- type: string
- format: url
- required: false
- examples:
- - https://better-auth.com
- default: http://localhost:3000
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- status:
- type: boolean
- examples:
- - true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Verification email isn't enabled
- - User not found
- '/verify-email':
- get:
- tags:
- - Email Verification
- summary: Verify email
- descriptions: It's used to verify email.
- operationId: verifyEmail
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- token:
- name: token
- in: query
- required: true
- schema:
- type: string
- format: uuid
- callbackURL:
- name: callbackURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- default: http://localhost:3000
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- user:
- '$ref': '#/components/schemas/User'
- nullable: true
- status:
- type: boolean
- examples:
- - true
- '302':
- description: Redirect
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Invalid token
- - User not found
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Session not found
- - Invalid session
- '/forget-password':
- post:
- tags:
- - Forget Password
- summary: Forget password
- descriptions: It's used to forget password.
- operationId: forgetPassword
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- examples:
- - bekacru@better-auth.com
- redirctTo:
- type: string
- format: url
- required: false
- examples:
- - https://better-auth.com
- default: http://localhost:3000
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- status:
- type: boolean
- examples:
- - true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Reset password isn't enabled
- '/reset-password/:token':
- get:
- tags:
- - Forget Password
- summary: Reset password with token
- descriptions: It's used to reset password with a token.
- operationId: resetPasswordToken
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- token:
- name: token
- in: path
- required: true
- schema:
- type: string
- format: uuid
- callbackURL:
- name: callbackURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- default: http://localhost:3000
- responses:
- '302':
- description: Redirect
- '/reset-password':
- post:
- tags:
- - Forget Password
- summary: Reset password
- descriptions: It's used to reset/set a new password.
- operationId: resetPassword
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- token:
- name: token
- in: query
- required: true
- schema:
- type: string
- format: uuid
- callbackURL:
- name: callbackURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- newPassword:
- type: string
- examples:
- - i-love-better-auth
- - better-auth-is-cool
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- status:
- type: boolean
- examples:
- - true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Token not found
- - Invalid token
- - Failed to update password
- '/sign-in/social':
- post:
- tags:
- - Sign in
- summary: Sign in with social account
- descriptions: It's used to sign in with social account.
- operationId: signInSocial
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- currentURL:
- name: currentURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- provider:
- type: string
- examples:
- - google
- - facebook
- - github
- - gitlab
- - twitter
- - linkedin
- - microsoft
- default: google
- callbackURL:
- type: string
- format: url
- required: false
- examples:
- - https://better-auth.com
- default: http://localhost:3000
- idToken:
- required: false
- type: object
- properties:
- token:
- type: string
- nonce:
- type: string
- required: false
- accessToken:
- type: string
- required: false
- refreshToken:
- type: string
- required: false
- expiresAt:
- type: integer
- format: int64
- required: false
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- user:
- '$ref': '#/components/schemas/User'
- nullable: true
- session:
- '$ref': '#/components/schemas/Session'
- nullable: true
- url:
- type: string
- format: url
- redirect:
- type: boolean
- examples:
- - true
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Invalid id token
- - Failed to get user info
- - User email not found
- '404':
- description: Not Found
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Provider not found
- - Provider does not support id token verification
- '/sign-in/email':
- post:
- tags:
- - Sign in
- summary: Sign in with email
- descriptions: It's used to sign in with email.
- operationId: signInEmail
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- examples:
- - bekacru@better-auth.com
- password:
- type: string
- examples:
- - i-love-better-auth
- callbackURL:
- type: string
- format: url
- required: false
- dontRememberMe:
- type: boolean
- examples:
- - true
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- user:
- '$ref': '#/components/schemas/User'
- nullable: true
- session:
- '$ref': '#/components/schemas/Session'
- nullable: true
- url:
- type: string
- format: url
- redirect:
- type: boolean
- examples:
- - true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Invalid email
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Email and password is not enabled
- - Invalid email or password
- - Unexpected error
- - Failed to create session
- '403':
- description: Forbidden
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Email is not verified. Check your email for a verification link
- '500':
- description: Internal Server Error
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Email is not verified.
- '/sign-out':
- post:
- tags:
- - Sign out
- summary: Sign out
- descriptions: It's used to sign out.
- operationId: signOut
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- status:
- type: boolean
- examples:
- - true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Session not found
- '/sign-up/email':
- post:
- tags:
- - Sign up
- summary: Sign up with email
- descriptions: It's used to sign up with email.
- operationId: signUpEmail
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- currentURL:
- name: currentURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- examples:
- - Bekacru
- email:
- type: string
- format: email
- examples:
- - bekacru@better-auth.com
- password:
- type: string
- examples:
- - i-love-better-auth
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- user:
- '$ref': '#/components/schemas/User'
- session:
- '$ref': '#/components/schemas/Session'
- nullable: true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Email and password sign up is not enabled
- - Invalid email
- - Password is too short
- - Password is too long
- - Failed to create user
- - Failed to create session
- '422':
- description: Unprocessable Entity
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - User with this email already exists
- - Failed to create user
- '/update-user':
- post:
- tags:
- - Update user
- summary: Update user
- descriptions: It's used to update user.
- operationId: updateUser
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- required: false
- type: string
- examples:
- - Bekacru
- image:
- required: false
- type: string
- format: url
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- user:
- '$ref': '#/components/schemas/User'
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - You can't update email
- '/change-password':
- post:
- tags:
- - Update user
- summary: Change password
- descriptions: It's used to change password.
- operationId: changePassword
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- currentPassword:
- type: string
- examples:
- - i-like-better-auth
- newPassword:
- type: string
- examples:
- - i-love-better-auth
- revokeOtherSessions:
- type: boolean
- examples:
- - true
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- '$ref': '#/components/schemas/User'
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Password is too short
- - Password too long
- - User does not have a password
- - Incorrect password
- '500':
- description: Internal Server Error
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Unable to create session
- '/set-password':
- post:
- tags:
- - Update user
- summary: Set password
- descriptions: It's used to set password.
- operationId: setPassword
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- newPassword:
- type: string
- examples:
- - i-love-better-auth
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- '$ref': '#/components/schemas/User'
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Password is too short
- - Password too long
- - user already has a password
- '/delete-user':
- post:
- tags:
- - Update user
- summary: Delete user
- descriptions: It's used to delete user.
- operationId: deleteUser
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- password:
- type: string
- examples:
- - i-love-better-auth
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: integer
- nullable: true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - User does not have a password
- - Incorrect password
- '/change-email':
- post:
- tags:
- - Update user
- summary: Change email
- descriptions: It's used to change email.
- operationId: changeEmail
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- currentURL:
- name: currentURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- newEmail:
- type: string
- format: email
- examples:
- - bekacru@better-auth.com
- callbackURL:
- type: string
- format: url
- required: false
- examples:
- - https://better-auth.com
- default: http://localhost:3000
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- user:
- '$ref': '#/components/schemas/User'
- nullable: true
- status:
- type: boolean
- examples:
- - true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Change email is disabled
- - Email is the same
- - Couldn't update your email
- - Verification email isn't enabled
-components:
- securitySchemes:
- bearerAuth:
- type: http
- scheme: bearer
- description: JWT Bearer token authentication
- apiKeyCookie:
- type: apiKey
- in: cookie
- name: api_key
- description: API key browser cookie
- responses:
- BadRequest:
- description: Bad Request
- content:
- application/json:
- schema:
- '$ref': '#/components/schemas/Error'
- Forbidden:
- description: Forbidden
- content:
- application/json:
- schema:
- '$ref': '#/components/schemas/Error'
- NotFound:
- description: NotFound
- content:
- application/json:
- schema:
- '$ref': '#/components/schemas/Error'
- Unauthorized:
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/schemas/Error'
- schemas:
- Session:
- type: object
- properties:
- session:
- type: object
- properties:
- id:
- type: string
- expiresAt:
- type: string
- format: date-time
- ipAddress:
- type: string
- format: ipv4
- example: 127.0.0.1
- userAgent:
- type: string
- userId:
- type: string
- format: uuid
- user:
- type: object
- properties:
- id:
- type: string
- name:
- type: string
- email:
- type: string
- format: email
- emailVerified:
- type: boolean
- image:
- type: string
- format: url
- createdAt:
- type: string
- format: date-time
- updatedAt:
- type: string
- format: date-time
- Account:
- type: object
- properties:
- id:
- type: string
- accountId:
- type: string
- providerId:
- type: string
- examples:
- - google
- - facebook
- - github
- - gitlab
- - twitter
- - linkedin
- - microsoft
- userId:
- type: string
- accessToken:
- type: string
- refreshToken:
- type: string
- idToken:
- type: string
- expiresAt:
- type: string
- format: date-time
- password:
- type: string
- User:
- type: object
- properties:
- id:
- type: string
- name:
- type: string
- email:
- type: string
- format: email
- emailVerified:
- type: boolean
- image:
- type: string
- format: url
- createdAt:
- type: string
- format: date-time
- updatedAt:
- type: string
- format: date-time
- Error:
- type: object
- description: RFC 7807 (https://datatracker.ietf.org/doc/html/rfc7807)
- properties:
- type:
- type: string
- examples:
- - https://example.com/errors/generic-error
- title:
- type: string
- examples:
- - Something went wrong here.
- status:
- type: integer
- format: int64
- examples:
- - 403
- detail:
- type: string
- examples:
- - Unfortunately, we can’t provide further information.
\ No newline at end of file
diff --git a/docs/package.json b/docs/package.json
index 03e93374..70762da6 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -7,7 +7,6 @@
"dev": "next dev",
"start": "next start",
"build:docs": "node ./scripts/generate-docs.mjs",
- "build:docs": "node ./scripts/generate-docs.mjs",
"typecheck": "tsc --noEmit",
"postinstall": "fumadocs-mdx"
},
diff --git a/docs/public/open-api-reference.png b/docs/public/open-api-reference.png
new file mode 100644
index 00000000..02866b31
Binary files /dev/null and b/docs/public/open-api-reference.png differ
diff --git a/docs/public/openapi.yml b/docs/public/openapi.yml
deleted file mode 100644
index 38d8db3f..00000000
--- a/docs/public/openapi.yml
+++ /dev/null
@@ -1,1341 +0,0 @@
-openapi: 3.1.1
-info:
- title: Better Auth API
- description: |
- The Better Auth API Endpoints gets documented here.
-
- ## Resources
-
- * https://github.com/better-auth/better-auth
- * https://better-auth.com
- version: 1.0.0
- contact:
- url: https://better-auth.com
-servers:
- - url: '{protocol}://{baseURL}/{path}'
- description: Responds with your request data
- variables:
- baseURL:
- default: 'localhost:3000'
- protocol:
- enum:
- - https
- default: https
- path:
- default: ''
-security:
- - bearerAuth: []
- - apiKeyCookie: []
-tags:
- - name: Sessions
- description: Everything about sessions
- - name: Account
- description: Everything about account
- - name: Callback
- description: Everything about callback
- - name: Email Verification
- description: Everything about email verification
- - name: Forget Password
- description: Everything about forget password
- - name: Sign in
- description: Everything about sign in
- - name: Sign out
- description: Everything about sign out
- - name: Sign up
- description: Everything about sign up
- - name: Update user
- description: Everything about update user
-paths:
- '/get-session':
- get:
- tags:
- - Sessions
- summary: Get current session
- descriptions: It's used to get the currently logged in session.
- operationId: getSession
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- '$ref': '#/components/schemas/Session'
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/responses/Unauthorized'
- '/list-sessions':
- get:
- tags:
- - Sessions
- summary: List all sessions
- descriptions: It's used to list all the sessions.
- operationId: listSessions
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: array
- items:
- '$ref': '#/components/schemas/Session'
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/responses/Unauthorized'
- '/revoke-session':
- post:
- tags:
- - Sessions
- summary: Revoke a session
- descriptions: It's used to revoke a session.
- operationId: revokeSession
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- requestBody:
- description: Session ID
- content:
- application/json:
- schema:
- type: object
- properties:
- id:
- type: string
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- status:
- type: boolean
- examples:
- - true
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/responses/Unauthorized'
- '/revoke-sessions':
- post:
- tags:
- - Sessions
- summary: Revoke all sessions
- descriptions: It's used to revoke all sessions.
- operationId: revokeSessions
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- status:
- type: boolean
- examples:
- - true
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/responses/Unauthorized'
- '/revoke-other-sessions':
- post:
- tags:
- - Sessions
- summary: Revoke other sessions
- descriptions: It's used to revoke all other sessions, other than the current one.
- operationId: revokeOtherSessions
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- status:
- type: boolean
- examples:
- - true
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/responses/Unauthorized'
- '/list-accounts':
- get:
- tags:
- - Account
- summary: List all accounts
- descriptions: It's used to list all the accounts linked to the current user.
- operationId: listAccounts
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: array
- items:
- '$ref': '#/components/schemas/Account'
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/responses/Unauthorized'
- '/link-social':
- post:
- tags:
- - Account
- summary: Link social account
- descriptions: It's used to link social account to the current user.
- operationId: linkSocial
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- currentURL:
- name: currentURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- provider:
- type: string
- examples:
- - google
- - facebook
- - github
- - gitlab
- - twitter
- - linkedin
- - microsoft
- default: google
- callbackURL:
- type: string
- format: url
- required: false
- examples:
- - https://better-auth.com
- default: http://localhost:3000
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- url:
- type: string
- format: url
- redirect:
- type: boolean
- examples:
- - true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Social Account is already linked.
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/responses/Unauthorized'
- '404':
- description: Not Found
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Provider not found
- '/callback/:id':
- get:
- tags:
- - Callback
- summary: Callback
- descriptions: It's used to callback the social account.
- operationId: callback
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- id:
- name: id
- in: path
- required: true
- schema:
- type: string
- state:
- name: state
- in: query
- required: true
- schema:
- type: string
- code:
- name: code
- in: query
- required: false
- schema:
- type: string
- error:
- name: error
- in: query
- required: false
- schema:
- type: string
- responses:
- '302':
- description: Redirect on error or success
- '/send-verification-email':
- post:
- tags:
- - Email Verification
- summary: Send verification email
- descriptions: It's used to send verification email.
- operationId: sendVerificationEmail
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- currentURL:
- name: currentURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- examples:
- - bekacru@better-auth.com
- callbackURL:
- type: string
- format: url
- required: false
- examples:
- - https://better-auth.com
- default: http://localhost:3000
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- status:
- type: boolean
- examples:
- - true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Verification email isn't enabled
- - User not found
- '/verify-email':
- get:
- tags:
- - Email Verification
- summary: Verify email
- descriptions: It's used to verify email.
- operationId: verifyEmail
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- token:
- name: token
- in: query
- required: true
- schema:
- type: string
- format: uuid
- callbackURL:
- name: callbackURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- default: http://localhost:3000
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- user:
- '$ref': '#/components/schemas/User'
- nullable: true
- status:
- type: boolean
- examples:
- - true
- '302':
- description: Redirect
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Invalid token
- - User not found
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Session not found
- - Invalid session
- '/forget-password':
- post:
- tags:
- - Forget Password
- summary: Forget password
- descriptions: It's used to forget password.
- operationId: forgetPassword
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- examples:
- - bekacru@better-auth.com
- redirctTo:
- type: string
- format: url
- required: false
- examples:
- - https://better-auth.com
- default: http://localhost:3000
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- status:
- type: boolean
- examples:
- - true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Reset password isn't enabled
- '/reset-password/:token':
- get:
- tags:
- - Forget Password
- summary: Reset password with token
- descriptions: It's used to reset password with a token.
- operationId: resetPasswordToken
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- token:
- name: token
- in: path
- required: true
- schema:
- type: string
- format: uuid
- callbackURL:
- name: callbackURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- default: http://localhost:3000
- responses:
- '302':
- description: Redirect
- '/reset-password':
- post:
- tags:
- - Forget Password
- summary: Reset password
- descriptions: It's used to reset/set a new password.
- operationId: resetPassword
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- token:
- name: token
- in: query
- required: true
- schema:
- type: string
- format: uuid
- callbackURL:
- name: callbackURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- newPassword:
- type: string
- examples:
- - i-love-better-auth
- - better-auth-is-cool
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- status:
- type: boolean
- examples:
- - true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Token not found
- - Invalid token
- - Failed to update password
- '/sign-in/social':
- post:
- tags:
- - Sign in
- summary: Sign in with social account
- descriptions: It's used to sign in with social account.
- operationId: signInSocial
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- currentURL:
- name: currentURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- provider:
- type: string
- examples:
- - google
- - facebook
- - github
- - gitlab
- - twitter
- - linkedin
- - microsoft
- default: google
- callbackURL:
- type: string
- format: url
- required: false
- examples:
- - https://better-auth.com
- default: http://localhost:3000
- idToken:
- required: false
- type: object
- properties:
- token:
- type: string
- nonce:
- type: string
- required: false
- accessToken:
- type: string
- required: false
- refreshToken:
- type: string
- required: false
- expiresAt:
- type: integer
- format: int64
- required: false
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- user:
- '$ref': '#/components/schemas/User'
- nullable: true
- session:
- '$ref': '#/components/schemas/Session'
- nullable: true
- url:
- type: string
- format: url
- redirect:
- type: boolean
- examples:
- - true
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Invalid id token
- - Failed to get user info
- - User email not found
- '404':
- description: Not Found
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Provider not found
- - Provider does not support id token verification
- '/sign-in/email':
- post:
- tags:
- - Sign in
- summary: Sign in with email
- descriptions: It's used to sign in with email.
- operationId: signInEmail
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- examples:
- - bekacru@better-auth.com
- password:
- type: string
- examples:
- - i-love-better-auth
- callbackURL:
- type: string
- format: url
- required: false
- dontRememberMe:
- type: boolean
- examples:
- - true
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- user:
- '$ref': '#/components/schemas/User'
- nullable: true
- session:
- '$ref': '#/components/schemas/Session'
- nullable: true
- url:
- type: string
- format: url
- redirect:
- type: boolean
- examples:
- - true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Invalid email
- '401':
- description: Unauthorized
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Email and password is not enabled
- - Invalid email or password
- - Unexpected error
- - Failed to create session
- '403':
- description: Forbidden
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Email is not verified. Check your email for a verification link
- '500':
- description: Internal Server Error
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Email is not verified.
- '/sign-out':
- post:
- tags:
- - Sign out
- summary: Sign out
- descriptions: It's used to sign out.
- operationId: signOut
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- status:
- type: boolean
- examples:
- - true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Session not found
- '/sign-up/email':
- post:
- tags:
- - Sign up
- summary: Sign up with email
- descriptions: It's used to sign up with email.
- operationId: signUpEmail
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- currentURL:
- name: currentURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- examples:
- - Bekacru
- email:
- type: string
- format: email
- examples:
- - bekacru@better-auth.com
- password:
- type: string
- examples:
- - i-love-better-auth
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- user:
- '$ref': '#/components/schemas/User'
- session:
- '$ref': '#/components/schemas/Session'
- nullable: true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Email and password sign up is not enabled
- - Invalid email
- - Password is too short
- - Password is too long
- - Failed to create user
- - Failed to create session
- '422':
- description: Unprocessable Entity
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - User with this email already exists
- - Failed to create user
- '/update-user':
- post:
- tags:
- - Update user
- summary: Update user
- descriptions: It's used to update user.
- operationId: updateUser
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- required: false
- type: string
- examples:
- - Bekacru
- image:
- required: false
- type: string
- format: url
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- user:
- '$ref': '#/components/schemas/User'
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - You can't update email
- '/change-password':
- post:
- tags:
- - Update user
- summary: Change password
- descriptions: It's used to change password.
- operationId: changePassword
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- currentPassword:
- type: string
- examples:
- - i-like-better-auth
- newPassword:
- type: string
- examples:
- - i-love-better-auth
- revokeOtherSessions:
- type: boolean
- examples:
- - true
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- '$ref': '#/components/schemas/User'
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Password is too short
- - Password too long
- - User does not have a password
- - Incorrect password
- '500':
- description: Internal Server Error
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Unable to create session
- '/set-password':
- post:
- tags:
- - Update user
- summary: Set password
- descriptions: It's used to set password.
- operationId: setPassword
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- newPassword:
- type: string
- examples:
- - i-love-better-auth
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- '$ref': '#/components/schemas/User'
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Password is too short
- - Password too long
- - user already has a password
- '/delete-user':
- post:
- tags:
- - Update user
- summary: Delete user
- descriptions: It's used to delete user.
- operationId: deleteUser
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- password:
- type: string
- examples:
- - i-love-better-auth
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: integer
- nullable: true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - User does not have a password
- - Incorrect password
- '/change-email':
- post:
- tags:
- - Update user
- summary: Change email
- descriptions: It's used to change email.
- operationId: changeEmail
- security:
- - bearerAuth: []
- - apiKeyCookie: []
- parameters:
- currentURL:
- name: currentURL
- in: query
- required: false
- schema:
- type: string
- format: url
- examples:
- - https://better-auth.com
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- newEmail:
- type: string
- format: email
- examples:
- - bekacru@better-auth.com
- callbackURL:
- type: string
- format: url
- required: false
- examples:
- - https://better-auth.com
- default: http://localhost:3000
- responses:
- '200':
- description: OK
- content:
- application/json:
- schema:
- type: object
- properties:
- user:
- '$ref': '#/components/schemas/User'
- nullable: true
- status:
- type: boolean
- examples:
- - true
- '400':
- description: Bad Request
- content:
- application/json:
- schema:
- type: object
- properties:
- message:
- type: string
- examples:
- - Change email is disabled
- - Email is the same
- - Couldn't update your email
- - Verification email isn't enabled
-components:
- securitySchemes:
- bearerAuth:
- type: http
- scheme: bearer
- description: JWT Bearer token authentication
- apiKeyCookie:
- type: apiKey
- in: cookie
- name: api_key
- description: API key browser cookie
- responses:
- BadRequest:
- description: Bad Request
- content:
- application/json:
- schema:
- '$ref': '#/components/schemas/Error'
- Forbidden:
- description: Forbidden
- content:
- application/json:
- schema:
- '$ref': '#/components/schemas/Error'
- NotFound:
- description: NotFound
- content:
- application/json:
- schema:
- '$ref': '#/components/schemas/Error'
- Unauthorized:
- description: Unauthorized
- content:
- application/json:
- schema:
- '$ref': '#/components/schemas/Error'
- schemas:
- Session:
- type: object
- properties:
- session:
- type: object
- properties:
- id:
- type: string
- expiresAt:
- type: string
- format: date-time
- ipAddress:
- type: string
- format: ipv4
- example: 127.0.0.1
- userAgent:
- type: string
- userId:
- type: string
- format: uuid
- user:
- type: object
- properties:
- id:
- type: string
- name:
- type: string
- email:
- type: string
- format: email
- emailVerified:
- type: boolean
- image:
- type: string
- format: url
- createdAt:
- type: string
- format: date-time
- updatedAt:
- type: string
- format: date-time
- Account:
- type: object
- properties:
- id:
- type: string
- accountId:
- type: string
- providerId:
- type: string
- examples:
- - google
- - facebook
- - github
- - gitlab
- - twitter
- - linkedin
- - microsoft
- userId:
- type: string
- accessToken:
- type: string
- refreshToken:
- type: string
- idToken:
- type: string
- expiresAt:
- type: string
- format: date-time
- password:
- type: string
- User:
- type: object
- properties:
- id:
- type: string
- name:
- type: string
- email:
- type: string
- format: email
- emailVerified:
- type: boolean
- image:
- type: string
- format: url
- createdAt:
- type: string
- format: date-time
- updatedAt:
- type: string
- format: date-time
- Error:
- type: object
- description: RFC 7807 (https://datatracker.ietf.org/doc/html/rfc7807)
- properties:
- type:
- type: string
- examples:
- - https://example.com/errors/generic-error
- title:
- type: string
- examples:
- - Something went wrong here.
- status:
- type: integer
- format: int64
- examples:
- - 403
- detail:
- type: string
- examples:
- - Unfortunately, we can’t provide further information.
\ No newline at end of file
diff --git a/packages/better-auth/package.json b/packages/better-auth/package.json
index 8c44b4ba..e26faddd 100644
--- a/packages/better-auth/package.json
+++ b/packages/better-auth/package.json
@@ -405,7 +405,7 @@
"@noble/hashes": "^1.5.0",
"@simplewebauthn/browser": "^10.0.0",
"@simplewebauthn/server": "^10.0.1",
- "better-call": "0.3.1",
+ "better-call": "0.3.2",
"consola": "^3.2.3",
"defu": "^6.1.4",
"jose": "^5.9.4",
diff --git a/packages/better-auth/src/api/routes/account.ts b/packages/better-auth/src/api/routes/account.ts
index adca7e5f..cb74d496 100644
--- a/packages/better-auth/src/api/routes/account.ts
+++ b/packages/better-auth/src/api/routes/account.ts
@@ -10,6 +10,34 @@ export const listUserAccounts = createAuthEndpoint(
{
method: "GET",
use: [sessionMiddleware],
+ metadata: {
+ openapi: {
+ description: "List all accounts linked to the user",
+ responses: {
+ "200": {
+ description: "Success",
+ content: {
+ "application/json": {
+ schema: {
+ type: "array",
+ items: {
+ type: "object",
+ properties: {
+ id: {
+ type: "string",
+ },
+ provider: {
+ type: "string",
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
},
async (c) => {
const session = c.context.session;
@@ -45,13 +73,45 @@ export const linkSocialAccount = createAuthEndpoint(
/**
* Callback URL to redirect to after the user has signed in.
*/
- callbackURL: z.string().optional(),
+ callbackURL: z
+ .string({
+ description: "The URL to redirect to after the user has signed in",
+ })
+ .optional(),
/**
* OAuth2 provider to use`
*/
- provider: z.enum(socialProviderList),
+ provider: z.enum(socialProviderList, {
+ description: "The OAuth2 provider to use",
+ }),
}),
use: [sessionMiddleware],
+ metadata: {
+ openapi: {
+ description: "Link a social account to the user",
+ responses: {
+ "200": {
+ description: "Success",
+ content: {
+ "application/json": {
+ schema: {
+ type: "object",
+ properties: {
+ url: {
+ type: "string",
+ },
+ redirect: {
+ type: "boolean",
+ },
+ },
+ required: ["url", "redirect"],
+ },
+ },
+ },
+ },
+ },
+ },
+ },
},
async (c) => {
const session = c.context.session;
diff --git a/packages/better-auth/src/api/routes/email-verification.ts b/packages/better-auth/src/api/routes/email-verification.ts
index 39d07dd5..ee6e5d63 100644
--- a/packages/better-auth/src/api/routes/email-verification.ts
+++ b/packages/better-auth/src/api/routes/email-verification.ts
@@ -38,13 +38,68 @@ export const sendVerificationEmail = createAuthEndpoint(
method: "POST",
query: z
.object({
- currentURL: z.string().optional(),
+ currentURL: z
+ .string({
+ description: "The URL to use for email verification callback",
+ })
+ .optional(),
})
.optional(),
body: z.object({
- email: z.string().email(),
- callbackURL: z.string().optional(),
+ email: z
+ .string({
+ description: "The email to send the verification email to",
+ })
+ .email(),
+ callbackURL: z
+ .string({
+ description: "The URL to use for email verification callback",
+ })
+ .optional(),
}),
+ metadata: {
+ openapi: {
+ description: "Send a verification email to the user",
+ requestBody: {
+ content: {
+ "application/json": {
+ schema: {
+ type: "object",
+ properties: {
+ email: {
+ type: "string",
+ description: "The email to send the verification email to",
+ },
+ callbackURL: {
+ type: "string",
+ description:
+ "The URL to use for email verification callback",
+ },
+ },
+ required: ["email"],
+ },
+ },
+ },
+ },
+ responses: {
+ "200": {
+ description: "Success",
+ content: {
+ "application/json": {
+ schema: {
+ type: "object",
+ properties: {
+ status: {
+ type: "boolean",
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
},
async (ctx) => {
if (!ctx.context.options.emailVerification?.sendVerificationEmail) {
@@ -85,9 +140,41 @@ export const verifyEmail = createAuthEndpoint(
{
method: "GET",
query: z.object({
- token: z.string(),
- callbackURL: z.string().optional(),
+ token: z.string({
+ description: "The token to verify the email",
+ }),
+ callbackURL: z
+ .string({
+ description: "The URL to redirect to after email verification",
+ })
+ .optional(),
}),
+ metadata: {
+ openapi: {
+ description: "Verify the email of the user",
+ responses: {
+ "200": {
+ description: "Success",
+ content: {
+ "application/json": {
+ schema: {
+ type: "object",
+ properties: {
+ user: {
+ type: "object",
+ },
+ status: {
+ type: "boolean",
+ },
+ },
+ required: ["user", "status"],
+ },
+ },
+ },
+ },
+ },
+ },
+ },
},
async (ctx) => {
function redirectOnError(error: string) {
diff --git a/packages/better-auth/src/api/routes/error.ts b/packages/better-auth/src/api/routes/error.ts
index 2d2def22..3704a2ec 100644
--- a/packages/better-auth/src/api/routes/error.ts
+++ b/packages/better-auth/src/api/routes/error.ts
@@ -87,7 +87,24 @@ export const error = createAuthEndpoint(
"/error",
{
method: "GET",
- metadata: HIDE_METADATA,
+ metadata: {
+ ...HIDE_METADATA,
+ openapi: {
+ description: "Displays an error page",
+ responses: {
+ "200": {
+ description: "Success",
+ content: {
+ "text/html": {
+ schema: {
+ type: "string",
+ },
+ },
+ },
+ },
+ },
+ },
+ },
},
async (c) => {
const query =
diff --git a/packages/better-auth/src/api/routes/forget-password.ts b/packages/better-auth/src/api/routes/forget-password.ts
index 22a657e5..2c810883 100644
--- a/packages/better-auth/src/api/routes/forget-password.ts
+++ b/packages/better-auth/src/api/routes/forget-password.ts
@@ -37,15 +37,47 @@ export const forgetPassword = createAuthEndpoint(
/**
* The email address of the user to send a password reset email to.
*/
- email: z.string().email(),
+ email: z
+ .string({
+ description:
+ "The email address of the user to send a password reset email to",
+ })
+ .email(),
/**
* The URL to redirect the user to reset their password.
* If the token isn't valid or expired, it'll be redirected with a query parameter `?
* error=INVALID_TOKEN`. If the token is valid, it'll be redirected with a query parameter `?
* token=VALID_TOKEN
*/
- redirectTo: z.string().optional(),
+ redirectTo: z
+ .string({
+ description:
+ "The URL to redirect the user to reset their password. If the token isn't valid or expired, it'll be redirected with a query parameter `?error=INVALID_TOKEN`. If the token is valid, it'll be redirected with a query parameter `?token=VALID_TOKEN",
+ })
+ .optional(),
}),
+ metadata: {
+ openapi: {
+ description: "Send a password reset email to the user",
+ responses: {
+ "200": {
+ description: "Success",
+ content: {
+ "application/json": {
+ schema: {
+ type: "object",
+ properties: {
+ status: {
+ type: "boolean",
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
},
async (ctx) => {
if (!ctx.context.options.emailAndPassword?.sendResetPassword) {
@@ -108,8 +140,32 @@ export const forgetPasswordCallback = createAuthEndpoint(
{
method: "GET",
query: z.object({
- callbackURL: z.string(),
+ callbackURL: z.string({
+ description: "The URL to redirect the user to reset their password",
+ }),
}),
+ metadata: {
+ openapi: {
+ description: "Redirects the user to the callback URL with the token",
+ responses: {
+ "200": {
+ description: "Success",
+ content: {
+ "application/json": {
+ schema: {
+ type: "object",
+ properties: {
+ token: {
+ type: "string",
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
},
async (ctx) => {
const { token } = ctx.params;
@@ -144,9 +200,37 @@ export const resetPassword = createAuthEndpoint(
),
method: "POST",
body: z.object({
- newPassword: z.string(),
- token: z.string().optional(),
+ newPassword: z.string({
+ description: "The new password to set",
+ }),
+ token: z
+ .string({
+ description: "The token to reset the password",
+ })
+ .optional(),
}),
+ metadata: {
+ openapi: {
+ description: "Reset the password for a user",
+ responses: {
+ "200": {
+ description: "Success",
+ content: {
+ "application/json": {
+ schema: {
+ type: "object",
+ properties: {
+ status: {
+ type: "boolean",
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
},
async (ctx) => {
const token =
diff --git a/packages/better-auth/src/api/routes/ok.ts b/packages/better-auth/src/api/routes/ok.ts
index fb816484..4e48cdd0 100644
--- a/packages/better-auth/src/api/routes/ok.ts
+++ b/packages/better-auth/src/api/routes/ok.ts
@@ -5,7 +5,29 @@ export const ok = createAuthEndpoint(
"/ok",
{
method: "GET",
- metadata: HIDE_METADATA,
+ metadata: {
+ ...HIDE_METADATA,
+ openapi: {
+ description: "Check if the API is working",
+ responses: {
+ "200": {
+ description: "Success",
+ content: {
+ "application/json": {
+ schema: {
+ type: "object",
+ properties: {
+ ok: {
+ type: "boolean",
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
},
async (ctx) => {
return ctx.json({
diff --git a/packages/better-auth/src/api/routes/session.ts b/packages/better-auth/src/api/routes/session.ts
index c4fde064..f25dec9c 100644
--- a/packages/better-auth/src/api/routes/session.ts
+++ b/packages/better-auth/src/api/routes/session.ts
@@ -26,13 +26,50 @@ export const getSession =