Home / How-to Guides
Edit
Report

Assign developers to a team with a Dev Portal custom sign-up form

Uses: Dev Portal Kong Gateway deck Konnect API
Incompatible with
on-prem
Related Documentation
Dev Portal Documentation
Tags
#application-registration #rbac
Related Resources
Dev Portal developer RBAC
Developer, API, and application registration forms
Review partner API access requests with Dev Portal custom forms
TL;DR

Create a custom developer registration form with a custom field, turn off developer auto-approve, then read each new developer’s additional_data and add them to the matching team using the /v3/portals/{portalId}/teams/{teamId}/developers endpoint before approving them.

Prerequisites

Kong Konnect

This is a Konnect tutorial and requires a Konnect personal access token.

  1. Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.

  2. Export your token to an environment variable:

    export KONNECT_TOKEN='YOUR_KONNECT_PAT'

  3. Run the quickstart script to automatically provision a Control Plane and Data Plane, and configure your environment:

    curl -Ls https://get.konghq.com/quickstart | bash -s -- -k $KONNECT_TOKEN \
     --deck-output

    This sets up a Konnect Control Plane named quickstart, provisions a local Data Plane, and prints out the following environment variable exports:

    export DECK_KONNECT_TOKEN=$KONNECT_TOKEN
export DECK_KONNECT_CONTROL_PLANE_NAME=quickstart
export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
export KONNECT_PROXY_URL='http://localhost:8000'

    Copy and paste these into your terminal to configure your session.

decK   v1.65.3+

To complete this tutorial, install decK. We recommend keeping decK up to date with the latest version (1.65.3).

decK is a CLI tool for managing Kong Gateway declaratively with state files. This guide uses deck gateway apply, which directly applies entity configuration to your Gateway instance.

You can check your current decK version with deck version.

Required entities

For this tutorial, you’ll need Kong Gateway entities, like Gateway Services and Routes, pre-configured. These entities are essential for Kong Gateway to function but installing them isn’t the focus of this guide. Follow these steps to pre-configure them:

  1. Run the following command:

    echo '
_format_version: "3.0"
services:
  - name: example-service
    url: http://httpbin.konghq.com/anything
routes:
  - name: example-route
    paths:
    - "/anything"
    service:
      name: example-service
    protocols:
    - http
    - https
' | deck gateway apply -

To learn more about entities, you can read our entities documentation.

Kong Konnect roles

To run this tutorial, you need the following Konnect teams and roles:

  • Portal Admin: Manage Dev Portal settings, teams, and custom forms.

Dev Portal

For this tutorial, you’ll need a Dev Portal and some Dev Portal settings pre-configured. These settings are essential for Dev Portal to function but configuring them isn’t the focus of this guide. If you don’t have these settings already configured, follow these steps to pre-configure them:

  1. Create a Dev Portal: 

    curl -X POST "https://us.api.konghq.com/v3/portals" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "MyDevPortal",
       "authentication_enabled": true,
       "auto_approve_applications": true,
       "auto_approve_developers": true,
       "default_api_visibility": "public",
       "default_page_visibility": "public"
     }'

  2. Export your Dev Portal ID and URL from the output:

    export PORTAL_ID='YOUR-DEV-PORTAL-ID'
export PORTAL_URL='YOUR-DEV-PORTAL-DOMAIN'

  3. Create a page in your Dev Portal so published APIs will display: 

    curl -X POST "https://us.api.konghq.com/v3/portals/$PORTAL_ID/pages" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "title": "My Page",
       "slug": "/",
       "description": "A custom page about developer portals",
       "visibility": "public",
       "status": "published",
       "content": "# Welcome to My Dev Portal\nExplore the available APIs below:\n::apis-list\n---\npersist-page-number: true\ncta-text: \"View APIs\"\n---\n"
     }'

Published API

  1. Create an API using the /v3/apis endpoint: 

    curl -X POST "https://us.api.konghq.com/v3/apis" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "MyAPI",
       "attributes": {
         "env": [
           "development"
         ],
         "domains": [
           "web",
           "mobile"
         ]
       }
     }'

    Export the ID of your API from the response:

    export API_ID='YOUR-API-ID'

  2. First, send a request to the /v2/control-planes endpoint to get the ID of the quickstart Control Plane: 

    curl -X GET "https://us.api.konghq.com/v2/control-planes?filter%5Bname%5D%5Bcontains%5D=quickstart" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

    Export your Control Plane ID:

    export CONTROL_PLANE_ID='YOUR-CONTROL-PLANE-ID'

  3. Next, list Services by using the /v2/control-planes/{controlPlaneId}/core-entities/services endpoint: 

    curl -X GET "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/core-entities/services" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

    Export the ID of the example-service:

    export SERVICE_ID='YOUR-GATEWAY-SERVICE-ID'

  4. Associate the API with a Service using the /v3/apis/{apiId}/implementations endpoint: 

    curl -X POST "https://us.api.konghq.com/v3/apis/$API_ID/implementations" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "service": {
         "control_plane_id": "'$CONTROL_PLANE_ID'",
         "id": "'$SERVICE_ID'"
       }
     }'

  5. Now you can publish the API to your Dev Portal using the /v3/apis/{apiId}/publications/{portalId} endpoint: 

    curl -X PUT "https://us.api.konghq.com/v3/apis/$API_ID/publications/$PORTAL_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

In this tutorial, you’ll collect a developer’s department at sign-up with a custom form, read that answer, add the developer to the matching team, and see them gain access to that team’s API. This can be useful when your Dev Portal is used internally by your organization’s own engineering groups, and you want new developers to be assigned to the right team, with the right API access, as soon as they’re approved.

Create teams

Create two teams, one for each department, by sending POST requests to the /portals/{portalId}/teams endpoint:

  1. Create the Payments team, and capture its ID as $PAYMENTS_TEAM_ID:

    PAYMENTS_TEAM_ID=$(curl -X POST "https://us.api.konghq.com/v3/portals/$PORTAL_ID/teams" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "Payments",
       "description": "The Payments engineering team"
     }' | jq -r ".id"
)

  2. Create the Platform team, and capture its ID as $PLATFORM_TEAM_ID:

    PLATFORM_TEAM_ID=$(curl -X POST "https://us.api.konghq.com/v3/portals/$PORTAL_ID/teams" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "Platform",
       "description": "The Platform engineering team"
     }' | jq -r ".id"
)

Give the Payments team API access

Give the Payments team access to your API, so its members can call it, by sending a POST request to the /portals/{portalId}/teams/{teamId}/assigned-roles endpoint:

curl -X POST "https://us.api.konghq.com/v3/portals/$PORTAL_ID/teams/$PAYMENTS_TEAM_ID/assigned-roles" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "role_name": "API Consumer",
       "entity_id": "'$SERVICE_ID'",
       "entity_type_name": "Services",
       "entity_region": "us"
     }'

The API Consumer role lets developers on the team make calls to the API. The Platform team is left without API access in this tutorial to show the difference in a developer’s access depending on which team they are assigned to.

Turn off auto-approve for developers

To review each new developer’s department answer and assign a team before they’re approved, turn off developer auto-approve by sending a PATCH request to the /portals/{portalId} endpoint:

curl -X PATCH "https://us.api.konghq.com/v3/portals/$PORTAL_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "auto_approve_developers": false
     }'

Application auto-approve is left on, since by the time a developer registers an application, their team already scopes what they can access.

Create a developer registration form

Create a custom form that asks new developers to select their department, by sending a POST request to the /portals/{portalId}/forms endpoint:

curl -X POST "https://us.api.konghq.com/v3/portals/$PORTAL_ID/forms" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "type": "developer_registration",
       "status": "published",
       "fields": [
         {
           "type": "text",
           "name": "full_name",
           "label": "Full name",
           "placeholder": "Enter your full name",
           "required": true
         },
         {
           "type": "email",
           "name": "email",
           "label": "Email address",
           "placeholder": "you@example.com",
           "required": true
         },
         {
           "type": "select",
           "mode": "single_select",
           "name": "department",
           "label": "Department",
           "required": true,
           "options": [
             {
               "value": "payments",
               "label": "Payments"
             },
             {
               "value": "platform",
               "label": "Platform"
             }
           ]
         },
         {
           "type": "submit",
           "name": "submit",
           "value": "Create account"
         }
       ]
     }'

Register a developer

Simulate a developer signing up and selecting their department, and capture their ID as $DEVELOPER_ID, by sending a POST request to the /portals/{portalId}/developers endpoint with additional_data:

DEVELOPER_ID=$(curl -X POST "https://us.api.konghq.com/v3/portals/$PORTAL_ID/developers" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "full_name": "Jordan Blake",
       "email": "jordan.blake@example.com",
       "additional_data": {
         "department": "payments"
       }
     }' | jq -r ".id"
)

Since auto-approve is off, this developer’s status is pending.

Read the submitted answer and assign a team

  1. Read the developer’s submitted answer, by sending a GET request to the /portals/{portalId}/developers/{developerId} endpoint:

    curl -X GET "https://us.api.konghq.com/v3/portals/$PORTAL_ID/developers/$DEVELOPER_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

    The response includes additional_data.department: payments.

  2. Based on that answer, add the developer to the matching team, by sending a POST request to the /portals/{portalId}/teams/{teamId}/developers endpoint:

    curl -X POST "https://us.api.konghq.com/v3/portals/$PORTAL_ID/teams/$PAYMENTS_TEAM_ID/developers" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "id": "'$DEVELOPER_ID'"
     }'

  3. Approve the developer, by sending a PATCH request to the /portals/{portalId}/developers/{developerId} endpoint:

    curl -X PATCH "https://us.api.konghq.com/v3/portals/$PORTAL_ID/developers/$DEVELOPER_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "status": "approved"
     }'

Validate

Verify that the developer was approved by sending a GET request to the /portals/{portalId}/developers/{developerId} endpoint and confirming status: approved in the response:

curl -X GET "https://us.api.konghq.com/v3/portals/$PORTAL_ID/developers/$DEVELOPER_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

Automation ideas

Instead of reading each developer’s answer and assigning their team manually, you can:

  • Run this logic on a schedule, or trigger it from an internal workflow tool whenever a new pending developer registers.
  • Extend the form with more departments as your organization grows, and maintain a lookup table mapping each department value to a team ID.

Dev Portal doesn’t have a webhook for new sign-ups, so this automation needs to poll the Konnect API on an interval, for example by listing developers filtered on status=pending.

Cleanup

Clean up Konnect environment

If you created a new control plane and want to conserve your free trial credits or avoid unnecessary charges, delete the new control plane used in this tutorial.

Something wrong?
Report an Issue | Edit this Page
View all Kong documentation

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!
Contribute

Still need help?

Ask in our Slack Community
Contact Support