151 lines
4.3 KiB
YAML
151 lines
4.3 KiB
YAML
openapi: 3.0.1
|
|
info:
|
|
title: Mainflux authentication service
|
|
description: HTTP API for managing platform API keys.
|
|
version: "1.0.0"
|
|
|
|
paths:
|
|
/keys:
|
|
post:
|
|
summary: Issue API key
|
|
description: |
|
|
Generates a new API key. Thew new API key will
|
|
be uniquely identified by its ID.
|
|
tags:
|
|
- auth
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/KeyRequest"
|
|
responses:
|
|
'201':
|
|
description: Issued new key.
|
|
'400':
|
|
description: Failed due to malformed JSON.
|
|
'409':
|
|
description: Failed due to using already existing ID.
|
|
'415':
|
|
description: Missing or invalid content type.
|
|
'500':
|
|
$ref: "#/components/responses/ServiceError"
|
|
/keys/{id}:
|
|
get:
|
|
summary: Gets API key details.
|
|
description: |
|
|
Gets API key details for the given key.
|
|
tags:
|
|
- auth
|
|
parameters:
|
|
- $ref: "#/components/parameters/ApiKeyId"
|
|
security:
|
|
- Authorization: []
|
|
responses:
|
|
'200':
|
|
$ref: "#/components/responses/KeyRes"
|
|
'400':
|
|
description: Failed due to malformed query parameters.
|
|
'403':
|
|
description: Missing or invalid access token provided.
|
|
'500':
|
|
$ref: "#/components/responses/ServiceError"
|
|
delete:
|
|
summary: Revoke API key
|
|
description: |
|
|
Revoke API key identified by the given ID.
|
|
tags:
|
|
- auth
|
|
parameters:
|
|
- $ref: "#/components/parameters/ApiKeyId"
|
|
security:
|
|
- Authorization: []
|
|
responses:
|
|
'204':
|
|
description: Key revoked.
|
|
'403':
|
|
description: Missing or invalid access token provided.
|
|
'500':
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
components:
|
|
securitySchemes:
|
|
Authorization:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: jwt
|
|
schemas:
|
|
Key:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
example: "c5747f2f-2a7c-4fe1-b41a-51a5ae290945"
|
|
description: API key unique identifier
|
|
issuer_id:
|
|
type: string
|
|
format: uuid
|
|
example: "9118de62-c680-46b7-ad0a-21748a52833a"
|
|
description: In ID of the entity that issued the token.
|
|
type:
|
|
type: integer
|
|
example: 0
|
|
description: API key type. Keys of different type are processed differently.
|
|
subject:
|
|
type: string
|
|
format: string
|
|
example: "test@example.com"
|
|
description: User's email or service identifier of API key subject.
|
|
issued_at:
|
|
type: string
|
|
format: date-time
|
|
example: "2019-11-26 13:31:52"
|
|
description: Time when the key is generated.
|
|
expires_at:
|
|
type: string
|
|
format: date-time
|
|
example: "2019-11-26 13:31:52"
|
|
description: Time when the Key expires. If this field is missing,
|
|
that means that Key is valid indefinitely.
|
|
|
|
parameters:
|
|
ApiKeyId:
|
|
name: id
|
|
description: API Key ID.
|
|
in: path
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
required: true
|
|
|
|
requestBodies:
|
|
KeyRequest:
|
|
description: JSON-formatted document describing key request.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: integer
|
|
example: 0
|
|
description: API key type. Keys of different type are processed differently.
|
|
token:
|
|
type: string
|
|
format: jwt
|
|
example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiZXhhbXBsZSIsImlhdCI6MTUxNjIzOTAyMn0.9UYAFWmPIn4ojss36LpIGSqABZHfADQmVuKQ4PJBMdI"
|
|
description: JWT for the entity that's sending Key request.
|
|
duration:
|
|
type: number
|
|
format: integer
|
|
example: 23456
|
|
description: Number of seconds issued token is valid for.
|
|
|
|
responses:
|
|
ServiceError:
|
|
description: Unexpected server-side error occurred.
|
|
KeyRes:
|
|
description: Data retrieved.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Key"
|