/v2/identities.createIdentity

[chronark]

Implement V2 Identity API Routes for Go

Background

We're migrating our API routes from the TypeScript implementation to a new Go API. The Go API will serve as V2 endpoints for our services. As part of this migration, we need to implement the identity creation functionality.

Assignment

Create a Go implementation of the existing TypeScript API route v1_identities_createIdentity.ts as a V2 endpoint. This should include:

1. Implementing the route handler in Go
2. Writing comprehensive tests similar to the TypeScript tests
3. Ensuring compatibility with the existing functionality

Reference Implementation

The existing TypeScript implementation is available in:

• unkey/apps/api/src/routes/v1_identities_createIdentity.ts
• unkey/apps/api/src/routes/v1_identities_createIdentity.happy.test.ts
• unkey/apps/api/src/routes/v1_identities_createIdentity.error.test.ts
• unkey/apps/api/src/routes/v1_identities_createIdentity.security.test.ts

The route allows creating identities with metadata and optional rate limits.

Requirements

Functional Requirements

• The new v2 endpoint should support all the same parameters as the v1 endpoint:

  • externalId (required): A unique identifier for the identity within your system
  • meta (optional): Metadata to attach to the identity
  • ratelimits (optional): Rate limit configurations

• Authentication via root keys with proper RBAC checks

• Response with the identityId of the newly created identity

Technical Requirements

• The implementation should follow our Go API patterns:

  • Use the zen framework for the HTTP handler
  • Implement proper validation
  • Use RBAC permissions checking
  • Structure your code in a testable way
  • Follow our error handling patterns with fault package

• Write comprehensive tests covering:

  • Happy path (successful creation)
  • Error cases (duplicate identities, validation errors)
  • Security tests (permissions, authentication)

Files Structure

Create your implementation in:

unkey/go/apps/api/routes/v2_identities_create_identity/

Follow the pattern used in other routes like the ratelimit routes we shared with you.

Resources

Please look at these existing Go routes for reference:

• unkey/go/apps/api/routes/v2_ratelimit_get_override
• unkey/go/apps/api/routes/v2_ratelimit_set_override

You can also see how we structure our Go code in the various packages under unkey/go/pkg/.

Expected Output

A complete implementation of the identity creation endpoint with supporting tests. Your code should be well-structured, properly tested, and follow our established patterns for Go API routes.

Code Generation

OpenAPI

Tool Used: oapi-codegen

How it works:

1. The API schema is defined in unkey/go/api/openapi.json, which is an OpenAPI specification file.
2. Code generation is triggered by go generate ./... which runs the command defined in unkey/go/api/generate.go:

//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen --config=config.yaml ./openapi.json

3. The generation is configured by unkey/go/api/config.yaml, which specifies:

   • Output package name
   • Output file (gen.go)
   • What to generate (models, in this case)

4. The result is a Go file with type definitions that match the API schema - allowing for type-safe API interactions.

Database Code Generation

Tool Used: sqlc

How it works:

1. SQL schemas and queries are defined in:

   • Schema: unkey/go/pkg/db/schema.sql (database table definitions)
   • Queries: Individual .sql files in unkey/go/pkg/db/queries/ (e.g., key_insert.sql, workspace_find_by_id.sql)

2. Code generation is triggered by go generate ./... which runs the command defined in unkey/go/pkg/db/generate.go:

//go:generate sqlc generate

3. The generation is configured by unkey/go/pkg/db/sqlc.json, which specifies:

   • Input queries directory
   • Schema file
   • Output configuration
   • Type mappings

4. For each SQL query file, sqlc generates:

   • Go structs representing the query parameters
   • Go structs representing the query results
   • Type-safe methods to execute the queries

How to Use It

1. When API Changes:

   • Update the OpenAPI spec in openapi.json
   • Run go generate ./...
   • Use the generated types in your code

2. When Database Changes:

   • Update the schema in schema.sql
   • Add/modify query files in the queries directory
   • Run go generate ./...
   • Use the generated query methods in your code with db.Query.MethodName()

Good luck!

[linear]

ENG-1663 /v2/identities/createIdentity

[Nelwhix]

@chronark I will give it a shot

[chronark]

hey @Nelwhix I created this issue for @Flo4604 to handle

[Nelwhix]

oh okay, can I help with the v2 migration?

[chronark]

we could use some help on other api endpoints, do you want to maybe start with one of the RBAC ones? like creating a permission?

[Nelwhix]

Alright, tag me on the issue once it is created