Topcoder Group API

Group API built on modern frameworks for managing all group-related Topcoder needs.

Use Node.js 26.5.1 and pnpm 11.15.1. Run nvm use in this project before running pnpm commands.

The production image runs as the unprivileged app user. Its Alpine 3.24 runtime installs Node.js >=26.5.1 and system OpenSSL >=3.5.8 from the Alpine repositories, allowing package updates while retaining the minimum patched versions. The Node.js build toolchain and npm are not copied into the runtime image.

Project setup

$ pnpm install

Compile and run the project

# development
$ pnpm run start

# watch mode
$ pnpm run start:dev

# production mode
$ pnpm run start:prod

Database

# run postgres in docker, or other approach
docker run -p 5432:5432  -e POSTGRES_PASSWORD=mysecretpassword postgres:14

export DATABASE_URL="postgresql://postgres:mysecretpassword@localhost:5432/group-api?schema=groups"

# run migration
pnpm exec prisma migrate dev

# seed data
pnpm exec prisma db seed
or
pnpm exec prisma migrate reset

# if you modify prisma schema, run migration again
# and it'll ask
# Enter a name for the new migration:
# just provide a good migration name, such as
#- `add_user_table`
#- `update_user_fields`
#- `create_posts_table`
#- `add_email_to_users`
#- `update_foreign_keys`

Data import

• create a .env file mv .env.sample .env
• update the postgres database url in .env file — DATABASE_URL="postgresql://postgres:mysecretpassword@localhost:5432/group-api?schema=groups"
• install dependencies pnpm install
• run the prisma migration pnpm exec prisma migrate dev
• run the prisma seed pnpm exec prisma db seed
• run the project pnpm run start

Test API

• import Postman collection. The files are doc/Group API.postman_collection.json and doc/Group.postman_environment.json
• set env to suit your environment
• run mock api node mock/mock-api.js
• reset seed data pnpm run seed-data
• start app pnpm run start:dev
• generate the token

curl --request POST \
  --url https://auth0proxy.topcoder-dev.com/token \
  --header 'content-type: application/json' \
  --data '{"auth0_url": "https://topcoder-dev.auth0.com/oauth/token", "client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"https://m2m.topcoder-dev.com/","grant_type":"client_credentials"}'

Obtain M2M credentials with the required scope from the approved secret store; never commit client credentials to this repository.

• then you can use Postman to test all apis
• Swagger docs are accessible at http://localhost:3000/api-docs

Downstream Usage

• This service is consumed by multiple Topcoder apps. Below is a quick map of where and how it’s called to help with debugging.

platform-ui

• Admin pages manage groups and memberships using v6 endpoints:
  • List/search groups: GET /v6/groups?page=1&perPage=10000 (optionally filter by name, or by memberId + membershipType=user). See platform-ui/src/apps/admin/src/lib/services/groups.service.ts.
  • Fetch group by id: GET /v6/groups/{id} (optional fields query). See platform-ui/src/apps/admin/src/lib/services/groups.service.ts.
  • List group members: GET /v6/groups/{id}/members?page&perPage. See platform-ui/src/apps/admin/src/lib/services/groups.service.ts.
  • Create group: POST /v6/groups. See platform-ui/src/apps/admin/src/lib/services/groups.service.ts.
  • Add member: POST /v6/groups/{id}/members with { membershipType: 'user'|'group', memberId }. See platform-ui/src/apps/admin/src/lib/services/groups.service.ts.
  • Remove member: DELETE /v6/groups/{id}/members/{memberId}. See platform-ui/src/apps/admin/src/lib/services/groups.service.ts.
• Local dev proxy maps both /v5/groups and /v6/groups to this service on port 3001. See platform-ui/src/config/environments/local.env.ts.

community-app

• Used server-side to expand community metadata group IDs to include descendants (group trees). The code acquires an M2M token and calls the groups service helper, which in turn queries the Groups API for a group’s tree of IDs. See community-app/src/server/services/communities.js and community-app/src/server/services/communities.js.
• Community App requires M2M credentials with access to Groups API for this logic. See community-app/README.md.
• Equivalent v6 endpoint for tree expansion is: GET /v6/groups/{id}?flattenGroupIdTree=true (also supports includeSubGroups, includeParentGroup, oneLevel).

work-manager

• Populates group selectors and filters challenge visibility:
  • Search groups by name for autocomplete: GET /v6/groups?name={query}&perPage={large}. See work-manager/src/components/ChallengeEditor/Groups-Field/index.js.
  • Load current user’s groups when creating/editing a challenge: GET /v6/groups?membershipType=user&memberId={tcUserId}&perPage={large}. See work-manager/src/actions/challenges.js.
  • Fetch group detail by id: GET /v6/groups/{id}. See work-manager/src/services/challenges.js.
• API base configuration points to v6 in dev/local and v5 in prod (for backward compatibility):
  • Dev: work-manager/config/constants/development.js.
  • Local: work-manager/config/constants/local.js and work-manager/config/constants/local.js.

Shared authentication and bus client (v6 refresh)

This branch uses tc-core-library-js 4.0.0-rc.1. Use its named createJwtVerifier / createJwtAuthenticator, createM2MClient, and createBusApiClient exports for shared authentication and bus API publishing. Service-specific roles, scopes, sessions and ownership checks remain in this service. The former bus wrapper dependency and local JWT cryptography must not be reintroduced.

RSA verification requires an exact configured issuer and audience (JWT_AUDIENCE for client tokens, AUTH0_AUDIENCE for machine/API tokens, or this service's explicit issuer-policy settings). HMAC secrets must be at least 32 bytes; no default secret is supplied. Expiry is enforced. Machine identity comes from the shared verifier, not the presence of scopes. Supply real development credentials through the service's existing environment configuration before deployment.

Bus publishers use createBusApiClient(config).postEvent(event) with the existing event envelope and optional key. Configure BUSAPI_URL for v6 and the existing OAuth credentials/token provider. The client uses bounded HTTPS requests and does not retry POSTs automatically. Application retry/outbox behavior remains local.

See the core migration guide for the API mapping, compatibility requirements, and rollout scope.