You are browsing documentation for an older version. See the latest documentation here.

Developers Reference
Available with Kong Gateway Enterprise subscription - Contact Sales

You can administer a Dev Portal instance through the Kong Admin API. Use the /developers API to:

Manage developers and applications
Create, update, and delete roles
Manage authentication for developers and applications

Note: The /developers API is part of the Kong Admin API, and is meant for bulk developer administration. This is not the same as the Dev Portal API /developer endpoints, which return data on the logged-in developer.

Developers

List all developers

Retrieve metadata for all developers.

Endpoint

/developers

Response

HTTP/1.1 200 OK

{
    "data": [
        {
            "consumer": {
                "id": "3f0ad41f-39b5-4fd0-ad1e-0b779fcee35c"
            },
            "created_at": 1644615612,
            "email": "some-email@example.com",
            "id": "3c6d4d8c-db86-4236-800b-8911e788425b",
            "meta": "{\"full_name\":\"Barry\"}",
            "roles": [
                "application developer"
            ],
            "status": 0,
            "updated_at": 1644615612
        },
        {
            "consumer": {
                "id": "9dbd764c-9548-4c9f-a4d1-6ea11e32a803"
            },
            "created_at": 1644615583,
            "email": "some-other-email@example.com",
            "id": "5f60930a-ad12-4303-ac5a-59d121ad4942",
            "meta": "{\"full_name\":\"Diana\"}",
            "roles": [
                "application developer"
            ],
            "status": 0,
            "updated_at": 1644615583
        }
    ],
    "next": null,
    "total": 2
}

Create a developer account

Create a new developer account.

All new developers are set to Requested Approval status by default, and must be changed to Approved before anyone can use the account.

You can approve developers through the Kong Manager, or approve the developer account as you’re creating it by setting the developer’s status manually.

Endpoint

/developers

Request body

Attribute	Description
`meta`	Metadata for the account in JSON format. Accepts fields defined in the Dev Portal settings. By default, the meta attribute requires a `full_name` field. You can remove this requirement, or add other fields as necessary. For example: `meta: {"full_name":"<NAME>"}`.
`email` required	The email of the developer to create. This becomes their login username.
`password` semi-optional	Create a password for the developer. Required if basic authentication is enabled.
`key` semi-optional	Assign an API key to the developer. Required if key authentication is enabled.
`id`	The developer entity ID. You can set your own UUID for this value, or leave it out to let Kong Gateway autogenerate a UUID.
`status`	The account approval status. If not provided, the status is set to `1` by default and developers are automatically placed in the Requested Access queue. Accepts one of the following integers: • `0` - Approved • `1` - Requested access • `2` - Rejected • `3` - Revoked

Example request:

curl -i -X POST http://localhost:8001/developers \
  --data email=example@example.com \
  --data meta="{\"full_name\":\"Wally\"}" \
  --data password=mypass \
  --data id=62d17e63-0628-43a3-b936-97b8dcbd366f

Response

HTTP/1.1 200 OK

{
    "consumer": {
        "id": "62d17e63-0628-43a3-b936-97b8dcbd366f"
    },
    "created_at": 1644616521,
    "email": "example@example.com",
    "id": "a82f9477-1a24-45b9-827c-23f1c1a7ebb3",
    "meta": "{\"full_name\":\"Wally\"}",
    "status": 0,
    "updated_at": 1644616521
}

Invite developers

Send invitations to a list of emails. SMTP must be enabled to send invite emails.

Endpoint

/developers/invite

Request body

Attribute	Description
`emails`	A comma-separated array of emails.

Example request:

curl -i -X POST http://localhost:8001/developers/invite \
  --data "emails[]=example@example.com" \
  --data "emails[]=example2@example.com"

Response

HTTP/1.1 200 OK

{
    "error": {
        "count": 0,
        "emails": {}
    },
    "sent": {
        "count": 2,
        "emails": {
            "example@example.com": true,
            "example2@example.com": true
        }
    },
    "smtp_mock": true
}

Inspect a developer

Retrieve metadata for a specific developer account.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of the developer you want to inspect.

Response

HTTP/1.1 200 OK

{
    "consumer": {
        "id": "855fe098-3bb3-4041-8a3d-149a9e5462c6"
    },
    "created_at": 1644617754,
    "email": "example@example.com",
    "id": "f94e4fbd-c30b-41d7-b349-13c8f4fc23ca",
    "rbac_user": {
        "id": "7d40540b-4b65-4fa6-b04e-ffe6c2c40b0d"
    },
    "roles": [
        "QA"
    ],
    "status": 0,
    "updated_at": 1644619493
}

Update a developer

Update the configuration or status for a specific developer account.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of the developer you want to update.

Request Body

Attribute	Description
`meta`	Metadata for the account in JSON format. Accepts fields defined in the Dev Portal settings. By default, the meta attribute requires a `full_name` field. You can remove this requirement, or add other fields as necessary. For example: `meta: {"full_name":"<NAME>"}`.
`email`	The email of the developer to create. This becomes their login username.
`status`	The account approval status. Accepts one of the following integers: • `0` - Approved • `1` - Requested access • `2` - Rejected • `3` - Revoked

Response

HTTP/1.1 200 OK

{
    "developer": {
        "consumer": {
            "id": "855fe098-3bb3-4041-8a3d-149a9e5462c6"
        },
        "created_at": 1644617754,
        "email": "example@example.com",
        "id": "f94e4fbd-c30b-41d7-b349-13c8f4fc23ca",
        "rbac_user": {
            "id": "7d40540b-4b65-4fa6-b04e-ffe6c2c40b0d"
        },
        "roles": [
            "QA"
        ],
        "status": 0,
        "updated_at": 1644621148
    }
}

Delete a developer

Delete a specific developer account.

Endpoint

/developers/{DEVELOPER_ID}

Attribute	Description
`{DEVELOPER_ID}`	The UUID of the developer you want to delete.

Response

HTTP/1.1 204 No Content

Export developer metadata

Prints a list of developers in CSV format.

/developers/export

Response

HTTP/1.1 200 OK

Email, Status
test@example.com,APPROVED
test1@example.com,PENDING
test2@example.com,REVOKED
test3@example.com,REJECTED

Roles

List all Dev Portal roles

List all RBAC roles configured for the Dev Portal.

By default, there are no roles. All Dev Portal roles are custom.

Endpoint

/developers/roles

Response

HTTP/1.1 200 OK

{
    "data": [
        {
            "created_at": 1644615388,
            "id": "525694de-776c-43ad-a940-769295d0c54e",
            "name": "Application Developer"
        },
        {
            "created_at": 1644619493,
            "id": "c8535760-e37f-4578-921f-04e781a3f8f1",
            "name": "QA"
        }
    ],
    "next": null,
    "total": 2
}

Create a Dev Portal role

Create an RBAC role for grouping developers.

When you create a role, by default, the role has no specific permissions and has access to all content in the Dev Portal. Use the Dev Portal > Permissions page in Kong Manager (<kong-manager-host:port>/<workspace-name>/portal/permissions/#roles) to specify permissions for the role.

Endpoint

/developers/roles

Request body

Attribute	Description
`name` required	A name for the role.
`comment`	A description of the role.

Response

HTTP/1.1 201 Created

{
    "comment": "Billing services team",
    "created_at": 1644620475,
    "id": "b7794758-394e-46f1-a9a1-f495f2e97a68",
    "name": "Billing",
    "permissions": {}
}

Inspect a role

Inspect a specific Dev Portal RBAC role.

Endpoint

/developers/roles/{ROLE_NAME|ROLE_ID}

Attribute	Description
`{ROLE_NAME\|ROLE_ID}` required	The name or UUID of the role you are inspecting.

Response

HTTP/1.1 200 OK

{
    "comment": "Billing services team",
    "created_at": 1644620475,
    "id": "b7794758-394e-46f1-a9a1-f495f2e97a68",
    "name": "Billing",
    "permissions": {}
}

Update a role

Update a specific Dev Portal RBAC role.

Endpoint

/developers/roles/{ROLE_NAME|ROLE_ID}

Attribute	Description
`{ROLE_NAME\|ROLE_ID}` required	The name or UUID of the role you are inspecting.

Request body

Attribute	Description
`name`	A name for the role.
`comment`	A description of the role.

Response

HTTP/1.1 200 OK

{
    "comment": "Billing services team",
    "created_at": 1644620475,
    "id": "b7794758-394e-46f1-a9a1-f495f2e97a68",
    "name": "Billing",
    "permissions": {}
}

Delete a role

Delete a specific Dev Portal RBAC role.

Endpoint

/developers/roles/{ROLE_NAME|ROLE_ID}

Attribute	Description
`{ROLE_NAME\|ROLE_ID}` required	The name or UUID of the role you are inspecting.

Response

HTTP/1.1 204 No Content

Applications

Applications consume Services in Kong Gateway via application-level authentication. Developers, or the persona that logs into the Dev Portal, create and manage applications through the Dev Portal.

Admins must first enable application registration through so that Developers can associate Services with applications.

List all applications for a developer

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/applications

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.

Response

HTTP/1.1 200 OK

{
    "data": [
        {
            "consumer": {
                "id": "6e31bf1e-dbcb-4a31-bac9-a192fa24f088"
            },
            "created_at": 1644963627,
            "developer": {
                "id": "5f60930a-ad12-4303-ac5a-59d121ad4942"
            },
            "id": "5ff48aaf-3951-4c99-a636-3b682081705c",
            "name": "example_app",
            "redirect_uri": "https://httpbin.konghq.com",
            "updated_at": 1644963627
        },
        {
            "consumer": {
                "id": "2390fd02-bbcd-48f1-b32f-89c262fa68a8"
            },
            "created_at": 1644963657,
            "developer": {
                "id": "5f60930a-ad12-4303-ac5a-59d121ad4942"
            },
            "id": "94e0f633-e8fd-4647-a0cd-4c3015ff2722",
            "name": "example_app2",
            "redirect_uri": "https://httpbin.konghq.com",
            "updated_at": 1644963657
        }
    ],
    "next": null,
    "total": 2
}

Inspect an application

Inspect a specific application using the application ID.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/applications/{APPLICATION_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{APPLICATION_ID}`	The application UUID.

Response

HTTP/1.1 200 OK

{
    "consumer": {
        "id": "d5ea9628-f359-4b96-9f76-61562aaf4300"
    },
    "created_at": 1644965555,
    "custom_id": "billing",
    "developer": {
        "id": "5f60930a-ad12-4303-ac5a-59d121ad4942"
    },
    "id": "ca0d62bd-4616-4b87-b947-43e33e5418f0",
    "name": "testapp",
    "redirect_uri": "https://httpbin.konghq.com",
    "updated_at": 1644965555
}

Create an application

Create a new application for a specific developer.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/applications

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.

Request body

Attribute	Description
`name` required	A name for the application.
`redirect_uri` required	The application’s URI.
`custom_id`	A custom name for the application. The `custom_id` is saved to the linked consumer entity for the application. This can be used for OIDC claim mapping when configuring the application’s `openid-connect` authentication plugin.

Response

HTTP/1.1 201 Created

{
    "consumer": {
        "id": "d5ea9628-f359-4b96-9f76-61562aaf4300"
    },
    "created_at": 1644965555,
    "custom_id": "billing-app",
    "developer": {
        "id": "5f60930a-ad12-4303-ac5a-59d121ad4942"
    },
    "id": "ca0d62bd-4616-4b87-b947-43e33e5418f0",
    "name": "testapp",
    "redirect_uri": "https://httpbin.konghq.com",
    "updated_at": 1644965555
}

Update an application

Update a specific application using the application ID.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/applications/{APPLICATION_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{APPLICATION_ID}`	The application UUID.

Request body

Attribute	Description
`name`	A name for the application.
`redirect_uri`	The application’s URI.
`custom_id`	A custom identifier for the application.

Response

HTTP/1.1 200 OK

{
    "consumer": {
        "id": "6e31bf1e-dbcb-4a31-bac9-a192fa24f088"
    },
    "created_at": 1644963627,
    "developer": {
        "id": "5f60930a-ad12-4303-ac5a-59d121ad4942"
    },
    "id": "5ff48aaf-3951-4c99-a636-3b682081705c",
    "name": "ExampleApp",
    "redirect_uri": "https://httpbin.konghq.com",
    "updated_at": 1645575611
}

Delete an application

Delete a specific application using the application ID.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/applications/{APPLICATION_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{APPLICATION_ID}`	The application UUID.

Response

HTTP/1.1 204 No Content

View all instances of an application

View all application instances that are connected to a Service in the Kong Gateway.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/applications/{APPLICATION_ID}/application_instances

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{APPLICATION_ID}`	The application UUID.

Response

HTTP/1.1 200 OK

{
    "data": [
        {
            "application": {
                "consumer": {
                    "id": "a4e8f835-e5bb-498c-8b6a-73a21c82776d"
                },
                "created_at": 1644965487,
                "developer": {
                    "consumer": {
                        "id": "9dbd764c-9548-4c9f-a4d1-6ea11e32a803"
                    },
                    "created_at": 1644615583,
                    "email": "example@example.com",
                    "id": "5f60930a-ad12-4303-ac5a-59d121ad4942",
                    "meta": "{\"full_name\":\"Wally\"}",
                    "rbac_user": {
                        "id": "431cae60-5d60-40be-8636-1b349a70a88d"
                    },
                    "status": 0,
                    "updated_at": 1644615874
                },
                "id": "645682ae-0be6-420a-bcf3-0e711a391546",
                "name": "testapp",
                "redirect_uri": "https://httpbin.konghq.com",
                "updated_at": 1644965487
            },
            "composite_id": "645682ae-0be6-420a-bcf3-0e711a391546_212a758a-810b-4226-9175-b1b44eecebec",
            "created_at": 1644968368,
            "id": "13fdfd32-8412-4479-b04f-a83d155e5de5",
            "service": {
                "id": "212a758a-810b-4226-9175-b1b44eecebec"
            },
            "status": 0,
            "suspended": false,
            "updated_at": 1644968411
        }
    ],
    "next": null,
    "total": 1
}

Create an application instance

Connect an application to a Service in the Kong Gateway.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/applications/{APPLICATION_ID}/application_instances

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{APPLICATION_ID}`	The application UUID.

Request body

Attribute	Description
`service.id`	The UUID of the Service to connect the application to.

Response

HTTP/1.1 201 Created

{
    "application": {
        "id": "5ff48aaf-3951-4c99-a636-3b682081705c"
    },
    "composite_id": "5ff48aaf-3951-4c99-a636-3b682081705c_212a758a-810b-4226-9175-b1b44eecebec",
    "created_at": 1645570372,
    "id": "50193ee0-372a-4694-874c-90ffbc0ae522",
    "service": {
        "id": "212a758a-810b-4226-9175-b1b44eecebec"
    },
    "status": 1,
    "suspended": false,
    "updated_at": 1645570372
}

Inspect an application instance

Get information about a specific instance of an application.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/applications/{APPLICATION_ID}/application_instances/{APPLICATION_INSTANCE_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{APPLICATION_ID}`	The application UUID.
`{APPLICATION_INSTANCE_ID}`	The application instance UUID.

Response

HTTP/1.1 200 OK

{
    "application": {
        "id": "645682ae-0be6-420a-bcf3-0e711a391546"
    },
    "composite_id": "645682ae-0be6-420a-bcf3-0e711a391546_212a758a-810b-4226-9175-b1b44eecebec",
    "created_at": 1644968368,
    "id": "13fdfd32-8412-4479-b04f-a83d155e5de5",
    "service": {
        "id": "212a758a-810b-4226-9175-b1b44eecebec"
    },
    "status": 0,
    "suspended": false,
    "updated_at": 1644968411
}

Update an application instance

Update a specific instance of an application.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/applications/{APPLICATION_ID}/application_instances/{APPLICATION_INSTANCE_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{APPLICATION_ID}`	The application UUID.
`{APPLICATION_INSTANCE_ID}`	The application instance UUID.

Request body

Attribute	Description
`service.id`	The UUID of the Service to connect the application to.

Response

HTTP/1.1 201 OK

{
    "application": {
        "id": "645682ae-0be6-420a-bcf3-0e711a391546"
    },
    "composite_id": "645682ae-0be6-420a-bcf3-0e711a391546_212a758a-810b-4226-9175-b1b44eecebec",
    "created_at": 1644968368,
    "id": "13fdfd32-8412-4479-b04f-a83d155e5de5",
    "service": {
        "id": "212a758a-810b-4226-9175-b1b44eecebec"
    },
    "status": 0,
    "suspended": false,
    "updated_at": 1644968411
}

Delete an application instance

Disconnect an application from a Service.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/applications/{APPLICATION_ID}/application_instances/{APPLICATION_INSTANCE_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{APPLICATION_ID}`	The application UUID.
`{APPLICATION_INSTANCE_ID}`	The application instance UUID.

Response

HTTP/1.1 204 No Content

Plugins

List all plugins

List all plugins for a developer.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/plugins

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.

Response

HTTP/1.1 200 OK

The exact response depends on the plugins that this developer has configured. For example, if there is a proxy-cache plugin enabled:

{
    "config": {
        "cache_control": false,
        "cache_ttl": 300,
        "content_type": [
            "text/plain",
            "application/json"
        ],
        "memory": {
            "dictionary_name": "kong_db_cache"
        },
        "request_method": [
            "GET",
            "HEAD"
        ],
        "response_code": [
            200,
            301,
            404
        ],
        "strategy": "memory"
    },
    "consumer": {
        "id": "bc504999-b3e5-4b08-8544-86962c969335"
    },
    "created_at": 1645564279,
    "enabled": true,
    "id": "d5f70fe4-58e6-4153-8569-07a1f901e751",
    "name": "proxy-cache",
    "protocols": [
        "grpc",
        "grpcs",
        "http",
        "https"
    ]
}

Apply a plugin

Configure a plugin and apply it to a developer.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/plugins

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.

Request body

Attribute	Description
`name` required	The name of a plugin to enable. You can use any plugin that can be enabled on a Consumer.
Plugin configuration fields	Any configuration parameters for the plugin that you are enabling. See the plugin’s reference on the Plugin Hub to find the parameters for a specific plugin.

Example request:

curl -i -X POST http://localhost:8001/developers/example@example.com/plugins \
  --data name=proxy-cache \
  --data config.strategy=memory

Response

HTTP/1.1 201 Created

The exact response depends on the plugin. For example, for proxy-cache:

{
    "config": {
        "cache_control": false,
        "cache_ttl": 300,
        "content_type": [
            "text/plain",
            "application/json"
        ],
        "memory": {
            "dictionary_name": "kong_db_cache"
        },
        "request_method": [
            "GET",
            "HEAD"
        ],
        "response_code": [
            200,
            301,
            404
        ],
        "strategy": "memory"
    },
    "consumer": {
        "id": "bc504999-b3e5-4b08-8544-86962c969335"
    },
    "created_at": 1645564279,
    "enabled": true,
    "id": "d5f70fe4-58e6-4153-8569-07a1f901e751",
    "name": "proxy-cache",
    "protocols": [
        "grpc",
        "grpcs",
        "http",
        "https"
    ]
}

Inspect a developer plugin

Inspect a plugin that is applied to a developer.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/plugins/{PLUGIN_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{PLUGIN_ID}`	The UUID of the plugin to inspect.

Response

HTTP/1.1 200 OK

The exact response depends on the plugin. For example, for proxy-cache:

{
    "config": {
        "cache_control": false,
        "cache_ttl": 300,
        "content_type": [
            "text/plain",
            "application/json"
        ],
        "memory": {
            "dictionary_name": "kong_db_cache"
        },
        "request_method": [
            "GET",
            "HEAD"
        ],
        "response_code": [
            200,
            301,
            404
        ],
        "strategy": "memory"
    },
    "consumer": {
        "id": "bc504999-b3e5-4b08-8544-86962c969335"
    },
    "created_at": 1645564279,
    "enabled": true,
    "id": "d5f70fe4-58e6-4153-8569-07a1f901e751",
    "name": "proxy-cache",
    "protocols": [
        "grpc",
        "grpcs",
        "http",
        "https"
    ]
}

Update a developer plugin

Edit a plugin that is applied to a developer.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/plugins/{PLUGIN_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{PLUGIN_ID}`	The UUID of the plugin to update.

Request body

Attribute	Description
Plugin configuration fields	Any configuration parameters for the plugin that you are editing. See the plugin’s reference on the Plugin Hub to find the parameters for a specific plugin.

Example request to update an instance of the proxy-cache plugin:

http PATCH :8001/developers/91a1fb59-d90f-4f07-b609-4c2a1e3d847e/plugins/d5f70fe4-58e6-4153-8569-07a1f901e751 \
  config.response_code:='[200, 301, 400, 404]'

Response

HTTP/1.1 200 OK

The exact response depends on the plugin. For example, if you change accepted response codes for proxy-cache to add 400:

{
    "config": {
        "cache_control": false,
        "cache_ttl": 300,
        "content_type": [
            "text/plain",
            "application/json"
        ],
        "memory": {
            "dictionary_name": "kong_db_cache"
        },
        "request_method": [
            "GET",
            "HEAD"
        ],
        "response_code": [
            200,
            301,
            400,
            404
        ],
        "strategy": "memory"
    },
    "consumer": {
        "id": "bc504999-b3e5-4b08-8544-86962c969335"
    },
    "created_at": 1645564279,
    "enabled": true,
    "id": "d5f70fe4-58e6-4153-8569-07a1f901e751",
    "name": "proxy-cache",
    "protocols": [
        "grpc",
        "grpcs",
        "http",
        "https"
    ]
}

Delete a developer plugin

Remove an authentication plugin from a developer.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/plugins/{PLUGIN_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{PLUGIN_ID}`	The UUID of the plugin to delete.

Response

HTTP/1.1 204 No Content

Developer authentication

Developers can authenticate to the Dev Portal using one of the following authentication methods:

Each of these methods configures an instance of the related Kong Gateway authentication plugin.

For a developer to be able to manage applications, the Dev Portal must use some kind of authentication, and each developer must be granted access to the Dev Portal. If authentication is disabled and the Dev Portal URL is public, application registration is not available.

Get all credentials

Get a list of all configured Dev Portal credentials for a specific type of authentication plugin.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/credentials/{PLUGIN_NAME}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{PLUGIN_NAME}`	The name of a supported authentication plugin. Can be one of: • `basic-auth` • `oauth2` • `hmac-auth` • `jwt` • `key-auth` • `openid-connect`

Response

HTTP/1.1 200 OK

The exact response depends on the plugin. For example, if you have two key-auth credentials:

{
    "data": [
        {
            "consumer": {
                "id": "bc504999-b3e5-4b08-8544-86962c969335"
            },
            "created_at": 1645566606,
            "id": "1a86d7eb-53ce-4a29-b573-a545e602fc05",
            "key": "testing"
        },
        {
            "consumer": {
                "id": "bc504999-b3e5-4b08-8544-86962c969335"
            },
            "created_at": 1645567499,
            "id": "1b0ba8f4-dd9f-4f68-8108-c81952e05b8e",
            "key": "wpJqvsTFRjgQstL16pQTYKtlHfkzdJpb"
        }
    ],
    "next": null,
    "total": 2
}

Create a credential

Create a Dev Portal credential. The credentials you can create depend on the type of authentication currently enabled for your Dev Portal.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/credentials/{PLUGIN_NAME}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{PLUGIN_NAME}`	The name of a supported authentication plugin. Can be one of: • `basic-auth` • `oauth2` • `hmac-auth` • `jwt` • `key-auth` • `openid-connect`

Request body

Attribute	Description
Plugin configuration fields	Any authentication credentials for the plugin that you are configuring. See the plugin’s reference documentation to find the parameters for a specific plugin: • `basic-auth` • `oauth2` • `hmac-auth` • `jwt` • `key-auth` • `openid-connect`

Example request for creating a key-auth credential:

curl -i -X POST http://localhost:8001/developers/91a1fb59-d90f-4f07-b609-4c2a1e3d847e/credentials/key-auth

Response

HTTP/1.1 201 Created

The exact response depends on the plugin. For example, if you add a key-auth credential:

{
    "consumer": {
        "id": "bc504999-b3e5-4b08-8544-86962c969335"
    },
    "created_at": 1645567499,
    "id": "1b0ba8f4-dd9f-4f68-8108-c81952e05b8e",
    "key": "wpJqvsTFRjgQstL16pQTYKtlHfkzdJpb"
}

Inspect a credential

Retrieve information about a specific Dev Portal credential using its ID.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/credentials/{PLUGIN_NAME}/{CREDENTIAL_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{PLUGIN_NAME}`	The name of a supported authentication plugin. Can be one of: • `basic-auth` • `oauth2` • `hmac-auth` • `jwt` • `key-auth` • `openid-connect`
`{CREDENTIAL_ID}`	The UUID of a credential for the plugin.

Response

HTTP/1.1 200 OK

The exact response depends on the plugin. For example, if you inspect a key-auth credential:

{
    "consumer": {
        "id": "bc504999-b3e5-4b08-8544-86962c969335"
    },
    "created_at": 1645567499,
    "id": "1b0ba8f4-dd9f-4f68-8108-c81952e05b8e",
    "key": "wpJqvsTFRjgQstL16pQTYKtlHfkzdJpb"
}

Update a credential

Update a specific Dev Portal credential.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/credentials/{PLUGIN_NAME}/{CREDENTIAL_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{PLUGIN_NAME}`	The name of a supported authentication plugin. Can be one of: Can be one of: • `basic-auth` • `oauth2` • `hmac-auth` • `jwt` • `key-auth` • `openid-connect`
`{CREDENTIAL_ID}`	The UUID of a credential for the plugin.

Request body

Attribute	Description
Plugin configuration fields	Any authentication credentials for the plugin that you are configuring. See the plugin’s reference documentation to find the parameters for a specific plugin: • `basic-auth` • `oauth2` • `hmac-auth` • `jwt` • `key-auth` • `openid-connect`

Example request to update a key-auth key:

http PATCH :8001/developers/91a1fb59-d90f-4f07-b609-4c2a1e3d847e/credentials/key-auth/1b0ba8f4-dd9f-4f68-8108-c81952e05b8e \
  key=apikey

Response

HTTP/1.1 200 OK

The exact response depends on the plugin. For example, if you update a key-auth credential to use a custom key instead of a UUID:

{
    "consumer": {
        "id": "bc504999-b3e5-4b08-8544-86962c969335"
    },
    "created_at": 1645567499,
    "id": "1b0ba8f4-dd9f-4f68-8108-c81952e05b8e",
    "key": "apikey"
}

Delete a credential

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/credentials/{PLUGIN_NAME}/{CREDENTIAL_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{PLUGIN_NAME}`	The name of a supported authentication plugin. Can be one of: • `basic-auth` • `oauth2` • `hmac-auth` • `jwt` • `key-auth` • `openid-connect`
`{CREDENTIAL_ID}`	The UUID of a credential for the plugin.

Response

HTTP/1.1 204 No Content

Application authentication

When application registration is enabled, it requires an authentication strategy. By default, this strategy is kong-oauth2, and it is set in kong.conf:

portal_app_auth = kong-oauth2

If you use the default strategy, you can configure authentication for applications using the following APIs. If using the external-oauth2 strategy, manage it through your IdP.

Inspect all credentials for an application

Get a list of all application credentials for a specific type of authentication plugin.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/applications/{APPLICATION_ID}/credentials/oauth2

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{APPLICATION_ID}`	The application UUID.

Response

HTTP/1.1 200 OK

{
    "data": [
        {
            "client_id": "3psqvdiojUKoJudqCh1U5P5mvR9k3zFF",
            "client_secret": "HUbYpUw8sNrEZGqyCs19HmRo08l9shC0",
            "client_type": "confidential",
            "consumer": {
                "id": "6e31bf1e-dbcb-4a31-bac9-a192fa24f088"
            },
            "created_at": 1644963627,
            "hash_secret": false,
            "id": "e22760bc-c6d4-4572-9814-132825286618",
            "name": "example_app",
            "redirect_uris": [
                "https://httpbin.konghq.com"
            ]
        }
    ],
    "next": null,
    "total": 1
}

Create a credential for an application

Create an OAuth2 authentication credential for an application. This request configures an instance of the OAuth2 plugin.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/applications/{APPLICATION_ID}/credentials/oauth2

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{APPLICATION_ID}`	The application UUID.

Request body

Attribute	Description
`client_id`	You can optionally set your own unique `client_id`. If not provided, the plugin will generate one.
`client_secret`	You can optionally set your own unique `client_secret`. If not provided, the plugin will generate one.
`redirect_uris`	An array with one or more URLs in your app where users will be sent after authorization (RFC 6742 Section 3.1.2).
`hash_secret`	A boolean flag that indicates whether the `client_secret` field will be stored in hashed form. If enabled on existing plugin instances, client secrets are hashed on the fly upon first usage. Default: `false`

Example request for creating an oauth2 credential:

curl -i -X POST http://localhost:8001/developers/5f60930a-ad12-4303-ac5a-59d121ad4942/applications/5ff48aaf-3951-4c99-a636-3b682081705c/credentials/oauth2 \ 
  --data client_id=myclient \
  --data client_secret=mysecret

Response

HTTP/1.1 201 Created

{
    "client_id": "t2vTlxxV1ANi9jFq2U1rlR1yp03Mi6uf",
    "client_secret": "EdKxXDD97LSe45lG5G5f6CBn5G9gXcp4",
    "client_type": "confidential",
    "consumer": {
        "id": "6e31bf1e-dbcb-4a31-bac9-a192fa24f088"
    },
    "created_at": 1645569439,
    "hash_secret": false,
    "id": "2dc8ee2a-ecfd-4ca5-a9c1-db371480e2cf",
    "name": "example_app",
    "redirect_uris": [
        "https://httpbin.konghq.com"
    ]
}

Inspect a credential for an application

Inspect an OAuth2 authentication credential of an application.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/applications/{APPLICATION_ID}/credentials/oauth2/{CREDENTIAL_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{APPLICATION_ID}`	The application UUID.
`{CREDENTIAL_ID}`	The UUID of a credential.

Response

HTTP/1.1 200 OK

{
    "client_id": "3psqvdiojUKoJudqCh1U5P5mvR9k3zFF",
    "client_secret": "HUbYpUw8sNrEZGqyCs19HmRo08l9shC0",
    "client_type": "confidential",
    "consumer": {
        "id": "6e31bf1e-dbcb-4a31-bac9-a192fa24f088"
    },
    "created_at": 1644963627,
    "hash_secret": false,
    "id": "e22760bc-c6d4-4572-9814-132825286618",
    "name": "example_app",
    "redirect_uris": [
        "https://httpbin.konghq.com"
    ]
}

Delete a credential from an application

Delete an OAuth2 authentication credential of an application.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/applications/{APPLICATION_ID}/credentials/oauth2/{CREDENTIAL_ID}

Attribute	Description
`{DEVELOPER_EMAIL\|DEVELOPER_ID}`	The email or UUID of a developer.
`{CREDENTIAL_ID}`	The UUID of a credential for the plugin.

Response

HTTP/1.1 204 No Content