このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
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.
Using the API in workspaces
Any requests that don’t specify a workspace target the default
workspace.
To target a different workspace, add /{WORKSPACE_NAME}/
to the start of any
endpoint.
For example, if you don’t specify a workspace,
this request retrieves a list of developers from the default
workspace:
While this request retrieves all developers from the workspace SRE
:
Developers
List all developers
Retrieve metadata for all developers.
Endpoint
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
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:
http POST :8001/developers \
email=example@example.com \
meta="{\"full_name\":\"Wally\"}" \
password=mypass \
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
Request body
Attribute | Description |
---|---|
emails |
A comma-separated array of emails. |
Example request:
http POST :8001/developers/invite emails:='["example@example.com", "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
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
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
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.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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:
http POST :8001/developers/example@example.com/plugins \
name=proxy-cache \
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
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
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
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
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
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:
http POST :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
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
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
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
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
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:
http POST :8001/developers/5f60930a-ad12-4303-ac5a-59d121ad4942/applications/5ff48aaf-3951-4c99-a636-3b682081705c/credentials/oauth2 client_id=myclient 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
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
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