chore: deprecate v1 endpoints

[chronark]

What does this PR do?

Marks all v1 API endpoints as deprecated and adds migration notices to their descriptions, directing users to the v2 API. This change helps guide users towards the newer API version while maintaining backward compatibility.

Fixes #

Type of change

• Enhancement (small improvements)
• Bug fix (non-breaking change which fixes an issue)
• Chore (refactoring code, technical debt, workflow improvements)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How should this be tested?

• Verify that all v1 endpoints in the OpenAPI spec are marked as deprecated
• Check that the deprecation notice appears in the API documentation
• Ensure the migration link (https://www.unkey.com/docs/api-reference/v1/migration) is correctly included in all endpoint descriptions

Checklist

Required

• Filled out the "How to test" section in this PR
• Read Contributing Guide
• Self-reviewed my own code
• Commented on my code in hard-to-understand areas
• Ran pnpm build
• Ran pnpm fmt
• Checked for warnings, there are none
• Removed all console.logs
• Merged the latest changes from main onto my branch with git pull origin main
• My changes don't cause any responsiveness issues

Appreciated

• If a UI change was made: Added a screen recording or screenshots to this PR
• Updated the Unkey Docs if changes were necessary

Summary by CodeRabbit

• Deprecations

  • All version 1 API endpoints are now marked as deprecated. Users are advised to migrate to version 2, with deprecation notices and migration links added to endpoint descriptions.

• Documentation

  • OpenAPI specifications updated to clarify deprecation status, improve schema references, and add descriptive tags for API groups.
  • Pagination cursor input for /v2/identities.listIdentities now provided in the request body instead of parameters.
  • Schema references for roles updated to use consistent lowercase naming.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2f4e7d2

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
dashboard	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 30, 2025 7:30am
engineering	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 30, 2025 7:30am

[coderabbitai]

📝 Walkthrough

Walkthrough

This change marks all v1 API routes in the project as deprecated by adding a deprecated: true flag and updating their descriptions with deprecation notices and migration guidance to v2, including documentation links. Additionally, OpenAPI specifications are updated to reflect schema reference changes, pagination input locations, and new tag metadata.

Changes

Cohort / File(s)	Change Summary
Deprecate all v1 API routes apps/api/src/routes/v1_analytics_getVerifications.ts, apps/api/src/routes/v1_apis_createApi.ts, apps/api/src/routes/v1_apis_deleteApi.ts, apps/api/src/routes/v1_apis_deleteKeys.ts, apps/api/src/routes/v1_apis_getApi.ts, apps/api/src/routes/v1_apis_listKeys.ts, apps/api/src/routes/v1_identities_createIdentity.ts, apps/api/src/routes/v1_identities_deleteIdentity.ts, apps/api/src/routes/v1_identities_getIdentity.ts, apps/api/src/routes/v1_identities_listIdentities.ts, apps/api/src/routes/v1_identities_updateIdentity.ts, apps/api/src/routes/v1_keys_addPermissions.ts, apps/api/src/routes/v1_keys_addRoles.ts, apps/api/src/routes/v1_keys_createKey.ts, apps/api/src/routes/v1_keys_deleteKey.ts, apps/api/src/routes/v1_keys_getKey.ts, apps/api/src/routes/v1_keys_getVerifications.ts, apps/api/src/routes/v1_keys_removePermissions.ts, apps/api/src/routes/v1_keys_removeRoles.ts, apps/api/src/routes/v1_keys_setPermissions.ts, apps/api/src/routes/v1_keys_setRoles.ts, apps/api/src/routes/v1_keys_updateKey.ts, apps/api/src/routes/v1_keys_updateRemaining.ts, apps/api/src/routes/v1_keys_verifyKey.ts, apps/api/src/routes/v1_keys_whoami.ts, apps/api/src/routes/v1_liveness.ts, apps/api/src/routes/v1_migrations_createKey.ts, apps/api/src/routes/v1_migrations_enqueueKeys.ts, apps/api/src/routes/v1_permissions_createPermission.ts, apps/api/src/routes/v1_permissions_createRole.ts, apps/api/src/routes/v1_permissions_deletePermission.ts, apps/api/src/routes/v1_permissions_deleteRole.ts, apps/api/src/routes/v1_permissions_getPermission.ts, apps/api/src/routes/v1_permissions_getRole.ts, apps/api/src/routes/v1_permissions_listPermissions.ts, apps/api/src/routes/v1_permissions_listRoles.ts, apps/api/src/routes/v1_ratelimits_deleteOverride.ts, apps/api/src/routes/v1_ratelimits_getOverride.ts, apps/api/src/routes/v1_ratelimits_limit.ts, apps/api/src/routes/v1_ratelimits_listOverrides.ts, apps/api/src/routes/v1_ratelimits_setOverride.ts	Added deprecated: true to each v1 route and updated descriptions with deprecation notices and migration documentation links. No functional changes to route logic.
OpenAPI spec: role schema reference and tags go/apps/api/openapi/openapi-generated.yaml, go/apps/api/openapi/openapi-split.yaml, go/apps/api/openapi/spec/paths/v2/permissions/getRole/V2PermissionsGetRoleResponseData.yaml, go/apps/api/openapi/spec/paths/v2/permissions/listRoles/V2PermissionsListRolesResponseData.yaml	Updated schema references from "Role" to "role", removed the "Role" schema, and added a top-level tags section with descriptions. Adjusted references in v2 permissions endpoints.
OpenAPI spec: pagination input location go/apps/api/openapi/spec/paths/v2/identities/listIdentities/index.yaml, go/apps/api/openapi/openapi-generated.yaml	Changed pagination cursor input for /v2/identities.listIdentities from request parameters to request body.
Go OpenAPI role struct relocation go/apps/api/openapi/gen.go	Moved the Role struct definition to a new location within the file; no changes to its structure.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant API Gateway
    participant v1 Route Handler

    Client->>API Gateway: Call v1 API endpoint
    API Gateway->>v1 Route Handler: Route request
    v1 Route Handler-->>API Gateway: Response (includes deprecation notice)
    API Gateway-->>Client: Response with deprecation warning in description

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• docs: analytics quickstarts #2807: Related as it modifies the same v1_analytics_getVerifications route, focusing on input validation and error handling.
• feat: Who Am I route #2159: Directly related; originally introduced the v1_keys_whoami.ts route, which is now being deprecated in this PR.

Suggested labels

:joystick: 150 points, 🕹️ oss.gg, Core Team

Suggested reviewers

• perkinsjr
• mcstepp

Note

⚡️ Unit Test Generation is now available in beta!

Learn more here, or try it out under "Finishing Touches" below.

✨ Finishing Touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch 07-30-chore_deprecate_v1_endpoints

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai generate unit tests to generate unit tests for this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[chronark]

• chore: deprecate v1 endpoints #3680 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

Thank you for following the naming conventions for pull request titles! 🙏

[coderabbitai]

Actionable comments posted: 22

🔭 Outside diff range comments (2)

apps/api/src/routes/v1_keys_removePermissions.ts (1)

119-131: deletePermissions stops after the first mismatch – permissions may be skipped

Early return inside the for … of loop exits the loop on the first non-matching delete request, so later requests are never evaluated.
Example: if the first deleteRequest doesn’t match the current permission but a later one would, the function returns false prematurely and the permission isn’t deleted.

-const deletePermissions = connectedPermissions.filter((cr) => {
-  for (const deleteRequest of req.permissions) {
-    if ("id" in deleteRequest) {
-      return cr.permissionId === deleteRequest.id;
-    }
-    if ("slug" in deleteRequest) {
-      return cr.permission.slug === deleteRequest.slug;
-    }
-    if ("name" in deleteRequest) {
-      return cr.permission.slug === deleteRequest.name;
-    }
-  }
-});
+const deletePermissions = connectedPermissions.filter((cr) =>
+  req.permissions.some((del) =>
+    "id" in del
+      ? cr.permissionId === del.id
+      : "slug" in del
+        ? cr.permission.slug === del.slug
+        : cr.permission.slug === del.name,
+  ),
+);

apps/api/src/routes/v1_identities_listIdentities.ts (1)

125-131: Wrong table referenced in cursor predicate – will break pagination

gt(schema.keys.id, req.cursor) compares the cursor against the keys table while the query targets identities.
This will always evaluate to false, preventing pagination.

-req.cursor ? gt(schema.keys.id, req.cursor) : undefined,
+req.cursor ? gt(schema.identities.id, req.cursor) : undefined,

♻️ Duplicate comments (10)

go/apps/api/openapi/spec/paths/v2/permissions/getRole/V2PermissionsGetRoleResponseData.yaml (1)

4-4: Same case-sensitivity concern as above

Confirm that common/role.yaml truly exists with lowercase to avoid broken schema refs.

apps/api/src/routes/v1_permissions_getRole.ts (1)

9-14: Same deprecation-flag location check

As with deleteIdentity, make sure the generator surfaces the deprecated: true flag in the output spec for /v1/permissions.getRole.

apps/api/src/routes/v1_identities_createIdentity.ts (1)

12-18: Same DRY suggestion as in v1_keys_setPermissions.ts

Reuse a shared constant for the deprecation message to keep wording consistent and maintenance trivial.

apps/api/src/routes/v1_keys_addPermissions.ts (1)

11-17: Same DRY suggestion as in v1_keys_setPermissions.ts

Factor the deprecation text into a shared constant.

apps/api/src/routes/v1_apis_deleteKeys.ts (1)

10-16: Same DRY suggestion as in v1_keys_setPermissions.ts

Move the repeated deprecation notice to a single constant.

apps/api/src/routes/v1_migrations_enqueueKeys.ts (1)

11-17: Same DRY suggestion as in v1_keys_setPermissions.ts

Centralise the deprecation notice string.

apps/api/src/routes/v1_keys_updateKey.ts (1)

15-22: Same duplication concern applies – see comment in v1_apis_getApi.ts.

apps/api/src/routes/v1_keys_addRoles.ts (1)

11-17: Same duplication concern applies – see comment in v1_apis_getApi.ts.

apps/api/src/routes/v1_permissions_listPermissions.ts (1)

8-14: Same duplication concern applies – see comment in v1_apis_getApi.ts.

apps/api/src/routes/v1_keys_setRoles.ts (1)

11-17: Same duplication concern applies – see comment in v1_apis_getApi.ts.