Developers Reference

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

  1. HTTP/1.1 200 OK
  1. {
  2. "data": [
  3. {
  4. "consumer": {
  5. "id": "3f0ad41f-39b5-4fd0-ad1e-0b779fcee35c"
  6. },
  7. "created_at": 1644615612,
  8. "email": "some-email@example.com",
  9. "id": "3c6d4d8c-db86-4236-800b-8911e788425b",
  10. "meta": "{\"full_name\":\"Barry\"}",
  11. "roles": [
  12. "application developer"
  13. ],
  14. "status": 0,
  15. "updated_at": 1644615612
  16. },
  17. {
  18. "consumer": {
  19. "id": "9dbd764c-9548-4c9f-a4d1-6ea11e32a803"
  20. },
  21. "created_at": 1644615583,
  22. "email": "some-other-email@example.com",
  23. "id": "5f60930a-ad12-4303-ac5a-59d121ad4942",
  24. "meta": "{\"full_name\":\"Diana\"}",
  25. "roles": [
  26. "application developer"
  27. ],
  28. "status": 0,
  29. "updated_at": 1644615583
  30. }
  31. ],
  32. "next": null,
  33. "total": 2
  34. }

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

AttributeDescription
metaMetadata 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.
idThe developer entity ID. You can set your own UUID for this value, or leave it out to let Kong Gateway autogenerate a UUID.
statusThe 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:

  1. http POST :8001/developers \
  2. email=example@example.com \
  3. meta="{\"full_name\":\"Wally\"}" \
  4. password=mypass \
  5. id=62d17e63-0628-43a3-b936-97b8dcbd366f

Response

  1. HTTP/1.1 200 OK
  1. {
  2. "consumer": {
  3. "id": "62d17e63-0628-43a3-b936-97b8dcbd366f"
  4. },
  5. "created_at": 1644616521,
  6. "email": "example@example.com",
  7. "id": "a82f9477-1a24-45b9-827c-23f1c1a7ebb3",
  8. "meta": "{\"full_name\":\"Wally\"}",
  9. "status": 0,
  10. "updated_at": 1644616521
  11. }

Invite developers

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

Endpoint

/developers/invite

Request body

AttributeDescription
emailsA comma-separated array of emails.

Example request:

  1. http POST :8001/developers/invite emails:='["example@example.com", "example2@example.com"]'

Response

  1. HTTP/1.1 200 OK
  1. {
  2. "error": {
  3. "count": 0,
  4. "emails": {}
  5. },
  6. "sent": {
  7. "count": 2,
  8. "emails": {
  9. "example@example.com": true,
  10. "example2@example.com": true
  11. }
  12. },
  13. "smtp_mock": true
  14. }

Inspect a developer

Retrieve metadata for a specific developer account.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of the developer you want to inspect.

Response

  1. HTTP/1.1 200 OK
  1. {
  2. "consumer": {
  3. "id": "855fe098-3bb3-4041-8a3d-149a9e5462c6"
  4. },
  5. "created_at": 1644617754,
  6. "email": "example@example.com",
  7. "id": "f94e4fbd-c30b-41d7-b349-13c8f4fc23ca",
  8. "rbac_user": {
  9. "id": "7d40540b-4b65-4fa6-b04e-ffe6c2c40b0d"
  10. },
  11. "roles": [
  12. "QA"
  13. ],
  14. "status": 0,
  15. "updated_at": 1644619493
  16. }

Update a developer

Update the configuration or status for a specific developer account.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of the developer you want to update.

Request Body

AttributeDescription
metaMetadata 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>”}.
emailThe email of the developer to create. This becomes their login username.
statusThe account approval status.

Accepts one of the following integers:
0 - Approved
1 - Requested access
2 - Rejected
3 - Revoked

Response

  1. HTTP/1.1 200 OK
  1. {
  2. "developer": {
  3. "consumer": {
  4. "id": "855fe098-3bb3-4041-8a3d-149a9e5462c6"
  5. },
  6. "created_at": 1644617754,
  7. "email": "example@example.com",
  8. "id": "f94e4fbd-c30b-41d7-b349-13c8f4fc23ca",
  9. "rbac_user": {
  10. "id": "7d40540b-4b65-4fa6-b04e-ffe6c2c40b0d"
  11. },
  12. "roles": [
  13. "QA"
  14. ],
  15. "status": 0,
  16. "updated_at": 1644621148
  17. }
  18. }

Delete a developer

Delete a specific developer account.

Endpoint

/developers/{DEVELOPER_ID}

AttributeDescription
{DEVELOPER_ID}The UUID of the developer you want to delete.

Response

  1. HTTP/1.1 204 No Content

Export developer metadata

Prints a list of developers in CSV format.

/developers/export

Response

  1. HTTP/1.1 200 OK
  1. Email, Status
  2. test@example.com,APPROVED
  3. test1@example.com,PENDING
  4. test2@example.com,REVOKED
  5. 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

  1. HTTP/1.1 200 OK
  1. {
  2. "data": [
  3. {
  4. "created_at": 1644615388,
  5. "id": "525694de-776c-43ad-a940-769295d0c54e",
  6. "name": "Application Developer"
  7. },
  8. {
  9. "created_at": 1644619493,
  10. "id": "c8535760-e37f-4578-921f-04e781a3f8f1",
  11. "name": "QA"
  12. }
  13. ],
  14. "next": null,
  15. "total": 2
  16. }

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

AttributeDescription
name
required
A name for the role.
commentA description of the role.

Response

  1. HTTP/1.1 201 Created
  1. {
  2. "comment": "Billing services team",
  3. "created_at": 1644620475,
  4. "id": "b7794758-394e-46f1-a9a1-f495f2e97a68",
  5. "name": "Billing",
  6. "permissions": {}
  7. }

Inspect a role

Inspect a specific Dev Portal RBAC role.

Endpoint

/developers/roles/{ROLE_NAME|ROLE_ID}

AttributeDescription
{ROLE_NAME|ROLE_ID}
required
The name or UUID of the role you are inspecting.

Response

  1. HTTP/1.1 200 OK
  1. {
  2. "comment": "Billing services team",
  3. "created_at": 1644620475,
  4. "id": "b7794758-394e-46f1-a9a1-f495f2e97a68",
  5. "name": "Billing",
  6. "permissions": {}
  7. }

Update a role

Update a specific Dev Portal RBAC role.

Endpoint

/developers/roles/{ROLE_NAME|ROLE_ID}

AttributeDescription
{ROLE_NAME|ROLE_ID}
required
The name or UUID of the role you are inspecting.

Request body

AttributeDescription
nameA name for the role.
commentA description of the role.

Response

  1. HTTP/1.1 200 OK
  1. {
  2. "comment": "Billing services team",
  3. "created_at": 1644620475,
  4. "id": "b7794758-394e-46f1-a9a1-f495f2e97a68",
  5. "name": "Billing",
  6. "permissions": {}
  7. }

Delete a role

Delete a specific Dev Portal RBAC role.

Endpoint

/developers/roles/{ROLE_NAME|ROLE_ID}

AttributeDescription
{ROLE_NAME|ROLE_ID}
required
The name or UUID of the role you are inspecting.

Response

  1. 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

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.

Response

  1. HTTP/1.1 200 OK
  1. {
  2. "data": [
  3. {
  4. "consumer": {
  5. "id": "6e31bf1e-dbcb-4a31-bac9-a192fa24f088"
  6. },
  7. "created_at": 1644963627,
  8. "developer": {
  9. "id": "5f60930a-ad12-4303-ac5a-59d121ad4942"
  10. },
  11. "id": "5ff48aaf-3951-4c99-a636-3b682081705c",
  12. "name": "example_app",
  13. "redirect_uri": "http://mockbin.org",
  14. "updated_at": 1644963627
  15. },
  16. {
  17. "consumer": {
  18. "id": "2390fd02-bbcd-48f1-b32f-89c262fa68a8"
  19. },
  20. "created_at": 1644963657,
  21. "developer": {
  22. "id": "5f60930a-ad12-4303-ac5a-59d121ad4942"
  23. },
  24. "id": "94e0f633-e8fd-4647-a0cd-4c3015ff2722",
  25. "name": "example_app2",
  26. "redirect_uri": "http://mockbin.org",
  27. "updated_at": 1644963657
  28. }
  29. ],
  30. "next": null,
  31. "total": 2
  32. }

Inspect an application

Inspect a specific application using the application ID.

Endpoint

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

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.
{APPLICATION_ID}The application UUID.

Response

  1. HTTP/1.1 200 OK
  1. {
  2. "consumer": {
  3. "id": "d5ea9628-f359-4b96-9f76-61562aaf4300"
  4. },
  5. "created_at": 1644965555,
  6. "custom_id": "billing",
  7. "developer": {
  8. "id": "5f60930a-ad12-4303-ac5a-59d121ad4942"
  9. },
  10. "id": "ca0d62bd-4616-4b87-b947-43e33e5418f0",
  11. "name": "testapp",
  12. "redirect_uri": "http://mockbin.org",
  13. "updated_at": 1644965555
  14. }

Create an application

Create a new application for a specific developer.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/applications

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.

Request body

AttributeDescription
name
required
A name for the application.
redirect_uri
required
The application’s URI.
custom_idA 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

  1. HTTP/1.1 201 Created
  1. {
  2. "consumer": {
  3. "id": "d5ea9628-f359-4b96-9f76-61562aaf4300"
  4. },
  5. "created_at": 1644965555,
  6. "custom_id": "billing-app",
  7. "developer": {
  8. "id": "5f60930a-ad12-4303-ac5a-59d121ad4942"
  9. },
  10. "id": "ca0d62bd-4616-4b87-b947-43e33e5418f0",
  11. "name": "testapp",
  12. "redirect_uri": "http://mockbin.org",
  13. "updated_at": 1644965555
  14. }

Update an application

Update a specific application using the application ID.

Endpoint

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

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.
{APPLICATION_ID}The application UUID.

Request body

AttributeDescription
nameA name for the application.
redirect_uriThe application’s URI.
custom_idA custom identifier for the application.

Response

  1. HTTP/1.1 200 OK
  1. {
  2. "consumer": {
  3. "id": "6e31bf1e-dbcb-4a31-bac9-a192fa24f088"
  4. },
  5. "created_at": 1644963627,
  6. "developer": {
  7. "id": "5f60930a-ad12-4303-ac5a-59d121ad4942"
  8. },
  9. "id": "5ff48aaf-3951-4c99-a636-3b682081705c",
  10. "name": "ExampleApp",
  11. "redirect_uri": "http://mockbin.org",
  12. "updated_at": 1645575611
  13. }

Delete an application

Delete a specific application using the application ID.

Endpoint

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

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.
{APPLICATION_ID}The application UUID.

Response

  1. 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

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.
{APPLICATION_ID}The application UUID.

Response

  1. HTTP/1.1 200 OK
  1. {
  2. "data": [
  3. {
  4. "application": {
  5. "consumer": {
  6. "id": "a4e8f835-e5bb-498c-8b6a-73a21c82776d"
  7. },
  8. "created_at": 1644965487,
  9. "developer": {
  10. "consumer": {
  11. "id": "9dbd764c-9548-4c9f-a4d1-6ea11e32a803"
  12. },
  13. "created_at": 1644615583,
  14. "email": "example@example.com",
  15. "id": "5f60930a-ad12-4303-ac5a-59d121ad4942",
  16. "meta": "{\"full_name\":\"Wally\"}",
  17. "rbac_user": {
  18. "id": "431cae60-5d60-40be-8636-1b349a70a88d"
  19. },
  20. "status": 0,
  21. "updated_at": 1644615874
  22. },
  23. "id": "645682ae-0be6-420a-bcf3-0e711a391546",
  24. "name": "testapp",
  25. "redirect_uri": "http://mockbin.org",
  26. "updated_at": 1644965487
  27. },
  28. "composite_id": "645682ae-0be6-420a-bcf3-0e711a391546_212a758a-810b-4226-9175-b1b44eecebec",
  29. "created_at": 1644968368,
  30. "id": "13fdfd32-8412-4479-b04f-a83d155e5de5",
  31. "service": {
  32. "id": "212a758a-810b-4226-9175-b1b44eecebec"
  33. },
  34. "status": 0,
  35. "suspended": false,
  36. "updated_at": 1644968411
  37. }
  38. ],
  39. "next": null,
  40. "total": 1
  41. }

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

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.
{APPLICATION_ID}The application UUID.

Request body

AttributeDescription
service.idThe UUID of the Service to connect the application to.

Response

  1. HTTP/1.1 201 Created
  1. {
  2. "application": {
  3. "id": "5ff48aaf-3951-4c99-a636-3b682081705c"
  4. },
  5. "composite_id": "5ff48aaf-3951-4c99-a636-3b682081705c_212a758a-810b-4226-9175-b1b44eecebec",
  6. "created_at": 1645570372,
  7. "id": "50193ee0-372a-4694-874c-90ffbc0ae522",
  8. "service": {
  9. "id": "212a758a-810b-4226-9175-b1b44eecebec"
  10. },
  11. "status": 1,
  12. "suspended": false,
  13. "updated_at": 1645570372
  14. }

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}

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.
{APPLICATION_ID}The application UUID.
{APPLICATION_INSTANCE_ID}The application instance UUID.

Response

  1. HTTP/1.1 200 OK
  1. {
  2. "application": {
  3. "id": "645682ae-0be6-420a-bcf3-0e711a391546"
  4. },
  5. "composite_id": "645682ae-0be6-420a-bcf3-0e711a391546_212a758a-810b-4226-9175-b1b44eecebec",
  6. "created_at": 1644968368,
  7. "id": "13fdfd32-8412-4479-b04f-a83d155e5de5",
  8. "service": {
  9. "id": "212a758a-810b-4226-9175-b1b44eecebec"
  10. },
  11. "status": 0,
  12. "suspended": false,
  13. "updated_at": 1644968411
  14. }

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}

AttributeDescription
{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

AttributeDescription
service.idThe UUID of the Service to connect the application to.

Response

  1. HTTP/1.1 201 OK
  1. {
  2. "application": {
  3. "id": "645682ae-0be6-420a-bcf3-0e711a391546"
  4. },
  5. "composite_id": "645682ae-0be6-420a-bcf3-0e711a391546_212a758a-810b-4226-9175-b1b44eecebec",
  6. "created_at": 1644968368,
  7. "id": "13fdfd32-8412-4479-b04f-a83d155e5de5",
  8. "service": {
  9. "id": "212a758a-810b-4226-9175-b1b44eecebec"
  10. },
  11. "status": 0,
  12. "suspended": false,
  13. "updated_at": 1644968411
  14. }

Delete an application instance

Disconnect an application from a Service.

Endpoint

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

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.
{APPLICATION_ID}The application UUID.
{APPLICATION_INSTANCE_ID}The application instance UUID.

Response

  1. HTTP/1.1 204 No Content

Plugins

List all plugins

List all plugins for a developer.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/plugins

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.

Response

  1. 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:

  1. {
  2. "config": {
  3. "cache_control": false,
  4. "cache_ttl": 300,
  5. "content_type": [
  6. "text/plain",
  7. "application/json"
  8. ],
  9. "memory": {
  10. "dictionary_name": "kong_db_cache"
  11. },
  12. "request_method": [
  13. "GET",
  14. "HEAD"
  15. ],
  16. "response_code": [
  17. 200,
  18. 301,
  19. 404
  20. ],
  21. "strategy": "memory"
  22. },
  23. "consumer": {
  24. "id": "bc504999-b3e5-4b08-8544-86962c969335"
  25. },
  26. "created_at": 1645564279,
  27. "enabled": true,
  28. "id": "d5f70fe4-58e6-4153-8569-07a1f901e751",
  29. "name": "proxy-cache",
  30. "protocols": [
  31. "grpc",
  32. "grpcs",
  33. "http",
  34. "https"
  35. ]
  36. }

Apply a plugin

Configure a plugin and apply it to a developer.

Endpoint

/developers/{DEVELOPER_EMAIL|DEVELOPER_ID}/plugins

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.

Request body

AttributeDescription
name
required
The name of a plugin to enable. You can use any plugin that can be enabled on a Consumer.
Plugin configuration fieldsAny 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:

  1. http POST :8001/developers/example@example.com/plugins \
  2. name=proxy-cache \
  3. config.strategy=memory

Response

  1. HTTP/1.1 201 Created

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

  1. {
  2. "config": {
  3. "cache_control": false,
  4. "cache_ttl": 300,
  5. "content_type": [
  6. "text/plain",
  7. "application/json"
  8. ],
  9. "memory": {
  10. "dictionary_name": "kong_db_cache"
  11. },
  12. "request_method": [
  13. "GET",
  14. "HEAD"
  15. ],
  16. "response_code": [
  17. 200,
  18. 301,
  19. 404
  20. ],
  21. "strategy": "memory"
  22. },
  23. "consumer": {
  24. "id": "bc504999-b3e5-4b08-8544-86962c969335"
  25. },
  26. "created_at": 1645564279,
  27. "enabled": true,
  28. "id": "d5f70fe4-58e6-4153-8569-07a1f901e751",
  29. "name": "proxy-cache",
  30. "protocols": [
  31. "grpc",
  32. "grpcs",
  33. "http",
  34. "https"
  35. ]
  36. }

Inspect a developer plugin

Inspect a plugin that is applied to a developer.

Endpoint

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

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.
{PLUGIN_ID}The UUID of the plugin to inspect.

Response

  1. HTTP/1.1 200 OK

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

  1. {
  2. "config": {
  3. "cache_control": false,
  4. "cache_ttl": 300,
  5. "content_type": [
  6. "text/plain",
  7. "application/json"
  8. ],
  9. "memory": {
  10. "dictionary_name": "kong_db_cache"
  11. },
  12. "request_method": [
  13. "GET",
  14. "HEAD"
  15. ],
  16. "response_code": [
  17. 200,
  18. 301,
  19. 404
  20. ],
  21. "strategy": "memory"
  22. },
  23. "consumer": {
  24. "id": "bc504999-b3e5-4b08-8544-86962c969335"
  25. },
  26. "created_at": 1645564279,
  27. "enabled": true,
  28. "id": "d5f70fe4-58e6-4153-8569-07a1f901e751",
  29. "name": "proxy-cache",
  30. "protocols": [
  31. "grpc",
  32. "grpcs",
  33. "http",
  34. "https"
  35. ]
  36. }

Update a developer plugin

Edit a plugin that is applied to a developer.

Endpoint

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

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.
{PLUGIN_ID}The UUID of the plugin to update.

Request body

AttributeDescription
Plugin configuration fieldsAny 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:

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

Response

  1. 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:

  1. {
  2. "config": {
  3. "cache_control": false,
  4. "cache_ttl": 300,
  5. "content_type": [
  6. "text/plain",
  7. "application/json"
  8. ],
  9. "memory": {
  10. "dictionary_name": "kong_db_cache"
  11. },
  12. "request_method": [
  13. "GET",
  14. "HEAD"
  15. ],
  16. "response_code": [
  17. 200,
  18. 301,
  19. 400,
  20. 404
  21. ],
  22. "strategy": "memory"
  23. },
  24. "consumer": {
  25. "id": "bc504999-b3e5-4b08-8544-86962c969335"
  26. },
  27. "created_at": 1645564279,
  28. "enabled": true,
  29. "id": "d5f70fe4-58e6-4153-8569-07a1f901e751",
  30. "name": "proxy-cache",
  31. "protocols": [
  32. "grpc",
  33. "grpcs",
  34. "http",
  35. "https"
  36. ]
  37. }

Delete a developer plugin

Remove an authentication plugin from a developer.

Endpoint

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

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.
{PLUGIN_ID}The UUID of the plugin to delete.

Response

  1. 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}

AttributeDescription
{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

  1. HTTP/1.1 200 OK

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

  1. {
  2. "data": [
  3. {
  4. "consumer": {
  5. "id": "bc504999-b3e5-4b08-8544-86962c969335"
  6. },
  7. "created_at": 1645566606,
  8. "id": "1a86d7eb-53ce-4a29-b573-a545e602fc05",
  9. "key": "testing"
  10. },
  11. {
  12. "consumer": {
  13. "id": "bc504999-b3e5-4b08-8544-86962c969335"
  14. },
  15. "created_at": 1645567499,
  16. "id": "1b0ba8f4-dd9f-4f68-8108-c81952e05b8e",
  17. "key": "wpJqvsTFRjgQstL16pQTYKtlHfkzdJpb"
  18. }
  19. ],
  20. "next": null,
  21. "total": 2
  22. }

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}

AttributeDescription
{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

AttributeDescription
Plugin configuration fieldsAny 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:

  1. http POST :8001/developers/91a1fb59-d90f-4f07-b609-4c2a1e3d847e/credentials/key-auth

Response

  1. HTTP/1.1 201 Created

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

  1. {
  2. "consumer": {
  3. "id": "bc504999-b3e5-4b08-8544-86962c969335"
  4. },
  5. "created_at": 1645567499,
  6. "id": "1b0ba8f4-dd9f-4f68-8108-c81952e05b8e",
  7. "key": "wpJqvsTFRjgQstL16pQTYKtlHfkzdJpb"
  8. }

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}

AttributeDescription
{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

  1. HTTP/1.1 200 OK

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

  1. {
  2. "consumer": {
  3. "id": "bc504999-b3e5-4b08-8544-86962c969335"
  4. },
  5. "created_at": 1645567499,
  6. "id": "1b0ba8f4-dd9f-4f68-8108-c81952e05b8e",
  7. "key": "wpJqvsTFRjgQstL16pQTYKtlHfkzdJpb"
  8. }

Update a credential

Update a specific Dev Portal credential.

Endpoint

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

AttributeDescription
{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

AttributeDescription
Plugin configuration fieldsAny 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:

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

Response

  1. 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:

  1. {
  2. "consumer": {
  3. "id": "bc504999-b3e5-4b08-8544-86962c969335"
  4. },
  5. "created_at": 1645567499,
  6. "id": "1b0ba8f4-dd9f-4f68-8108-c81952e05b8e",
  7. "key": "apikey"
  8. }

Delete a credential

Endpoint

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

AttributeDescription
{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

  1. 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:

  1. 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

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.
{APPLICATION_ID}The application UUID.

Response

  1. HTTP/1.1 200 OK
  1. {
  2. "data": [
  3. {
  4. "client_id": "3psqvdiojUKoJudqCh1U5P5mvR9k3zFF",
  5. "client_secret": "HUbYpUw8sNrEZGqyCs19HmRo08l9shC0",
  6. "client_type": "confidential",
  7. "consumer": {
  8. "id": "6e31bf1e-dbcb-4a31-bac9-a192fa24f088"
  9. },
  10. "created_at": 1644963627,
  11. "hash_secret": false,
  12. "id": "e22760bc-c6d4-4572-9814-132825286618",
  13. "name": "example_app",
  14. "redirect_uris": [
  15. "http://mockbin.org"
  16. ]
  17. }
  18. ],
  19. "next": null,
  20. "total": 1
  21. }

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

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.
{APPLICATION_ID}The application UUID.

Request body

AttributeDescription
client_idYou can optionally set your own unique client_id. If not provided, the plugin will generate one.
client_secretYou can optionally set your own unique client_secret. If not provided, the plugin will generate one.
redirect_urisAn array with one or more URLs in your app where users will be sent after authorization (RFC 6742 Section 3.1.2).
hash_secretA 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:

  1. http POST :8001/developers/5f60930a-ad12-4303-ac5a-59d121ad4942/applications/5ff48aaf-3951-4c99-a636-3b682081705c/credentials/oauth2 client_id=myclient client_secret=mysecret

Response

  1. HTTP/1.1 201 Created
  1. {
  2. "client_id": "t2vTlxxV1ANi9jFq2U1rlR1yp03Mi6uf",
  3. "client_secret": "EdKxXDD97LSe45lG5G5f6CBn5G9gXcp4",
  4. "client_type": "confidential",
  5. "consumer": {
  6. "id": "6e31bf1e-dbcb-4a31-bac9-a192fa24f088"
  7. },
  8. "created_at": 1645569439,
  9. "hash_secret": false,
  10. "id": "2dc8ee2a-ecfd-4ca5-a9c1-db371480e2cf",
  11. "name": "example_app",
  12. "redirect_uris": [
  13. "http://mockbin.org"
  14. ]
  15. }

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}

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.
{APPLICATION_ID}The application UUID.
{CREDENTIAL_ID}The UUID of a credential.

Response

  1. HTTP/1.1 200 OK
  1. {
  2. "client_id": "3psqvdiojUKoJudqCh1U5P5mvR9k3zFF",
  3. "client_secret": "HUbYpUw8sNrEZGqyCs19HmRo08l9shC0",
  4. "client_type": "confidential",
  5. "consumer": {
  6. "id": "6e31bf1e-dbcb-4a31-bac9-a192fa24f088"
  7. },
  8. "created_at": 1644963627,
  9. "hash_secret": false,
  10. "id": "e22760bc-c6d4-4572-9814-132825286618",
  11. "name": "example_app",
  12. "redirect_uris": [
  13. "http://mockbin.org"
  14. ]
  15. }

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}

AttributeDescription
{DEVELOPER_EMAIL|DEVELOPER_ID}The email or UUID of a developer.
{CREDENTIAL_ID}The UUID of a credential for the plugin.

Response

  1. HTTP/1.1 204 No Content