This repository has been archived on 2024-07-27. You can view files and clone it, but cannot push or open issues or pull requests.
keksAccount/public/docs/api.yml
2019-07-23 17:48:11 +02:00

1022 lines
30 KiB
YAML

swagger: "2.0"
info:
description: "API Dokumentation for keksAccount oAuth Service."
version: "1.0.0"
title: "KeksAccount"
contact:
email: "admin@keks.cloud"
license:
name: "Apache 2.0"
url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "api.account.keks.cloud"
basePath: "/api/v1"
tags:
- name: "account"
description: "The User-Account"
- name: "user"
description: "Register and Login to an Account"
- name: "admin"
description: "Calls for the Admin users only"
- name: "apps"
description: "Information and Actions about Apps"
schemes:
- "https"
paths:
/user/register:
post:
tags:
- "user"
summary: "Register a new Account"
description: "Possible if registration is enabled or the request contains a valide invide"
produces:
- "application/json"
consumes:
- "multipart/form-data"
- "application/json"
parameters:
- in: formData
name: username
description: "Username for the new User"
required: true
type: string
- in: formData
name: password
description: "Password for the new User"
required: true
type: string
- in: formData
name: mail
description: "A valide E-Mail adress for the User"
required: true
type: string
- in: formData
name: invite
description: "If the user have an invite code to create the account"
required: false
type: string
- in: formData
name: g-recaptcha-response
description: "If google recaptcha is enabled for account creation this parameter is requierd"
required: false
type: string
responses:
200:
description: "User Account crated"
schema:
type: "object"
properties:
data:
$ref: '#/definitions/User'
success:
type: "boolean"
example: true
msg:
type: "string"
example: ""
400:
description: "Register disabled, you may can register with an valide invite code"
schema:
type: "object"
properties:
success:
type: "boolean"
example: false
msg:
type: "string"
example: "Registration disabled"
422:
description: "Some of the data ar missing or invalide, see data in the response object for details"
schema:
type: "object"
properties:
data:
type: "object"
properties:
username:
type: array
items:
type: string
example: "The username field is required."
password:
type: array
items:
type: string
example: "The password field is required."
mail:
type: array
items:
type: string
example: "The mail field is required."
success:
type: "boolean"
example: false
msg:
type: "string"
example: "The given data was invalid."
/user/login:
post:
tags:
- "user"
summary: "Login to an Account with Username/Passwort"
description: "Login with Passwort for the keksAccount GUI, dont use this in your Application."
produces:
- "application/json"
consumes:
- "multipart/form-data"
- "application/json"
parameters:
- in: formData
name: username
description: "Username"
required: true
type: string
- in: formData
name: password
description: "Password"
required: true
type: string
responses:
200:
description: "Login succesfull"
schema:
type: "object"
properties:
data:
type: "object"
properties:
access_token:
type: "string"
description: "Access Token for the user"
token_type:
type: "string"
description: "Typ of the Token"
example: ""
success:
type: "boolean"
example: true
msg:
type: "string"
example: ""
400:
description: "Register disabled, you may can register with an valide invite code"
schema:
type: "object"
properties:
success:
type: "boolean"
example: false
msg:
type: "string"
example: "Registration disabled"
422:
description: "Some of the data ar missing or invalide, see data in the response object for details"
schema:
type: "object"
properties:
data:
type: "object"
properties:
username:
type: array
items:
type: string
example: "The username field is required."
password:
type: array
items:
type: string
example: "The password field is required."
success:
type: "boolean"
example: false
msg:
type: "string"
example: "The given data was invalid."
/user/captcha:
get:
tags:
- "user"
summary: "Return the Captcha Key and Settings"
description: "Return the Google Recaptcha Key and the list of actions the captcha is enabled/required for"
produces:
- "application/json"
responses:
200:
description: "Captcha Informations"
schema:
type: "object"
properties:
data:
type: "object"
properties:
key:
type: "string"
description: "Pubplic Recaptcha code"
login:
type: "boolean"
description: "Show captcha if the User want to loging"
example: true
register:
type: "boolean"
description: "Show captcha if the User want to register"
example: true
success:
type: "boolean"
example: true
msg:
type: "string"
example: ""
/user/invites:
get:
tags:
- "user"
summary: "Return information about an invite code"
description: ""
produces:
- "application/json"
parameters:
- in: query
name: code
description: "The invite code"
required: true
type: string
responses:
200:
description: "Captcha Informations"
schema:
type: "object"
properties:
data:
type: "object"
properties:
usable:
type: "boolean"
example: true
description: "If the value is true the invite code is valide and can be used to register a new account"
username:
type: "string"
description: "If a username is set the user have to use this username for the registration"
example: ""
success:
type: "boolean"
example: true
msg:
type: "string"
example: ""
404:
description: "Invite code not found"
schema:
type: "object"
properties:
success:
type: "boolean"
example: false
msg:
type: "string"
example: "Resource not Found"
/user/me:
get:
tags:
- "user"
summary: "Return information about the current User"
description: ""
produces:
- "application/json"
responses:
200:
description: "Found user and return informations"
schema:
type: "object"
properties:
data:
$ref: '#/definitions/User'
success:
type: "boolean"
example: true
msg:
type: "string"
example: ""
401:
description: "Not logged in"
schema:
type: "object"
properties:
success:
type: "boolean"
example: false
msg:
type: "string"
example: "You need to login"
/account:
get:
tags:
- "account"
- "admin"
summary: "ADMIN! Return a list of all users"
description: "Return a list with all users in the system."
parameters:
- in: query
name: page
description: "Which page should be returned"
required: false
type: string
responses:
200:
description: "Found user and return informations"
schema:
type: "object"
properties:
data:
type: array
items:
$ref: '#/definitions/User'
success:
type: "boolean"
example: true
msg:
type: "string"
example: ""
pagination:
type: "object"
properties:
currentPage:
type: integer
pageCount:
type: integer
itemsPerPage:
type: integer
401:
description: "Not logged in"
schema:
type: "object"
properties:
success:
type: "boolean"
example: false
msg:
type: "string"
example: "You need to login"
403:
description: "You dont have the permission to see this data"
schema:
type: "object"
properties:
success:
type: "boolean"
example: false
msg:
type: "string"
example: "You need to login"
/account/{id}:
get:
tags:
- "account"
- "admin"
summary: "ADMIN! Return a User object"
description: ""
parameters:
- in: path
name: id
description: "User ID to get details from"
required: true
type: string
responses:
200:
description: "Found user and return informations"
schema:
type: "object"
properties:
data:
$ref: '#/definitions/User'
success:
type: "boolean"
example: true
msg:
type: "string"
example: ""
pagination:
type: "object"
properties:
currentPage:
type: integer
pageCount:
type: integer
itemsPerPage:
type: integer
401:
description: "Not logged in"
schema:
type: "object"
properties:
success:
type: "boolean"
example: false
msg:
type: "string"
example: "You need to login"
403:
description: "You dont have the permission to see this data"
schema:
type: "object"
properties:
success:
type: "boolean"
example: false
msg:
type: "string"
example: "You need to login"
/app:
get:
tags:
- "apps"
summary: "Return a list of the Users Apps"
description: ""
responses:
200:
description: "List of Apps"
schema:
type: "object"
properties:
data:
type: array
items:
$ref: '#/definitions/AppForOwner'
success:
type: "boolean"
example: true
msg:
type: "string"
example: ""
pagination:
type: "object"
properties:
currentPage:
type: integer
pageCount:
type: integer
itemsPerPage:
type: integer
post:
tags:
- "apps"
summary: "Create a new APP"
description: ""
produces:
- "application/json"
consumes:
- "multipart/form-data"
- "application/json"
parameters:
- in: formData
name: name
description: "Name of the app"
required: true
type: string
- in: formData
name: description
description: "Description of the App"
required: true
type: string
- in: formData
name: url
description: "App Webpage URL"
required: true
type: string
responses:
200:
description: "List of Apps"
schema:
type: "object"
properties:
data:
$ref: '#/definitions/AppForOwner'
success:
type: "boolean"
example: true
msg:
type: "string"
example: ""
/app/find:
get:
tags:
- "apps"
summary: "Find Apps on the given Informations"
description: "If no paramtes are given it will return a complete list of all Apps"
parameters:
- in: query
name: apiKey
description: "Search an app based on the API-Key"
required: false
type: string
- in: query
name: webpage
description: "Return Apps shown on the Startpage"
required: false
type: boolean
responses:
200:
description: "List of Apps"
schema:
type: "object"
properties:
data:
type: array
items:
$ref: '#/definitions/App'
success:
type: "boolean"
example: true
msg:
type: "string"
example: ""
pagination:
type: "object"
properties:
currentPage:
type: integer
pageCount:
type: integer
itemsPerPage:
type: integer
/app/{id}:
get:
tags:
- "apps"
summary: "Return information about an app"
description: "If the User is owner of the App it will return a AppForOwner Object, if not just an App bject."
parameters:
- in: path
name: id
description: "App ID"
required: true
type: string
responses:
200:
description: "List of Apps"
schema:
type: "object"
properties:
data:
$ref: '#/definitions/App'
success:
type: "boolean"
example: true
msg:
type: "string"
example: ""
put:
tags:
- "apps"
summary: "Update App Details"
description: ""
produces:
- "application/json"
consumes:
- "multipart/form-data"
- "application/json"
parameters:
- in: path
name: id
required: true
type: integer
- in: formData
name: name
description: "Name of the app"
required: false
type: string
- in: formData
name: description
description: "Description of the App"
required: false
type: string
- in: formData
name: url
description: "App Webpage URL"
required: false
type: string
- in: formData
name: direct_url
description: "Direct Login URL"
required: false
type: string
responses:
200:
description: "List of Apps"
schema:
type: "object"
properties:
data:
$ref: '#/definitions/AppForOwner'
success:
type: "boolean"
example: true
msg:
type: "string"
example: ""
/app/{id}/access:
get:
tags:
- "apps"
- "oAuth"
summary: "Return Access Information about the current user and this App"
description: "If the App is auto_accept it will direct creat and return a access object with allowd status. If status is allowed you can redirect the user back to the app."
produces:
- "application/json"
consumes:
- "multipart/form-data"
- "application/json"
parameters:
- in: path
name: id
description: "App ID"
required: true
type: string
responses:
200:
description: "List of Apps"
schema:
type: "object"
properties:
data:
$ref: '#/definitions/AppAccess'
success:
type: "boolean"
example: true
msg:
type: "string"
example: ""
/app/{id}/access/allow:
post:
tags:
- "apps"
- "oAuth"
summary: "Set the Access to allow and return an appCode/redirectURL"
description: "If the user clicks on the 'Login to XY' button this endpoint create the code for the App and a return url, the gui redirect the User to this url to finish the login"
produces:
- "application/json"
consumes:
- "multipart/form-data"
- "application/json"
parameters:
- in: path
name: id
description: "App ID"
required: true
type: string
- in: formData
name: redirect_uri
description: "The Redirect URL given by the App as GET-Paremter"
required: true
type: string
- in: formData
name: state
description: "Give from the APP as GET-Parameter"
required: false
type: string
responses:
200:
description: "List of Apps"
schema:
type: "object"
properties:
data:
type: "object"
properties:
appCode:
type: string
description: "Code for the App to create a oAuth Bear and oAuth Refresh token with"
redirectUrl:
type: string
description: "URL to redirect the user to, contains all needet informations."
success:
type: "boolean"
example: true
msg:
type: "string"
example: ""
/oauth/authorize:
get:
tags:
- "oAuth"
summary: "Entry Point for Apps to start oAuth workflow"
consumes:
- "multipart/form-data"
- "application/json"
parameters:
- in: query
name: client_id
description: "API-Key for the App the login should be started"
required: true
type: string
- in: query
name: redirect_uri
description: "URL to redirect the user back if he want to join the app"
required: true
type: string
- in: query
name: state
description: "Param from the App, added to the redirect url"
required: false
type: string
responses:
200:
description: Return a HTML view or redirect the user to a HTML-View to give Access to the App
/oauth/token:
post:
tags:
- "oAuth"
summary: "Get Beare Access Token and Refresh Token from AppCode"
consumes:
- "multipart/form-data"
- "application/json"
parameters:
- in: formData
name: code
description: "Code give from the GET-Request the user is redirectet to."
required: true
type: string
responses:
200:
description: Token is valide, the user has logged in
schema:
type: object
properties:
access_token:
type: string
description: Access Token (bearer)
token_type:
type: string
example: "bearer"
expires_in:
type: integer
example: 3600
description: How long until the tolen expired
refresh_token:
type: string
description: "Refresh tolen to create a new Access Token"
/server/settings:
get:
tags:
- "server"
summary: "Get the Server-Settings"
parameters:
- in: query
name: all
description: "Admin! Return all Settings"
required: false
type: boolean
responses:
200:
description: Token is valide, the user has logged in
schema:
type: object
properties:
data:
type: "array"
items:
type: object
properties:
name:
type: string
description: Name of the Setting
description:
type: string
description: "Description what the setting is doing"
typ:
type: string
description: "What kind of setting is it"
enum:
- checkbox
- textinput
- password
value:
type: string
description: "Value, type based on the typ of the setting"
success:
type: "boolean"
example: true
msg:
type: "string"
example: ""
definitions:
User:
type: "object"
properties:
id:
type: "integer"
format: "int64"
example: 18
username:
type: "string"
example: "testaccount"
created_at:
type: "string"
format: "DateTime"
example: "2019-07-17T13:37:40.000000Z"
updated_at:
type: "string"
format: "DateTime"
example: "2019-07-17T13:37:40.000000Z"
primaryMail:
type: "string"
format: "mail"
example: "mail@example.com"
status:
type: "string"
description: "Account Status"
example: "active"
enum:
- "active"
inviteCode:
type: "string"
example: "sdjfios"
description: "Invite Code used to register this Account"
developer:
type: "boolean"
example: false
description: "If the user is a developer Account (Can create new Apps)"
admin:
type: "boolean"
example: false
description: "If the user is a admin Account"
AppForOwner:
type: "object"
properties:
id:
type: integer
description: "ID of the APP"
example: 42
created_at:
type: string
description: "Time the App was created"
example: "2019-04-25T13:54:29.000000Z"
updated_at:
type: string
description: "Last time the App was updated"
example: "2019-07-17T09:23:13.000000Z"
name:
type: string
description: "Name of the App"
example: "Gitea"
description:
type: string
description: "Description of the App"
example: "Self-hostet Git server for our organisation"
url:
type: string
description: "URL of the Webpage of the App"
example: "https://git.keks.cloud"
directUrl:
type: string
description: "Link to log the user in the App, if the user is alweady give access to the App this link should rederect the user direct to the Dashboard"
example: "https://git.keks.cloud/user/oauth2/KeksAccount"
apiKey:
type: string
description: "The API-Key for the App"
apiSecret:
type: string
description: "The API-Secret for the App"
properties:
type: object
properties:
testingWarning:
type: boolean
description: "Show a warning at the App-Page that the App is in Testing-Modus"
autoAccept:
type: boolean
description: "User don't have to accept to go to the app, if user is at the oAuth-Accept page he will direct redirect to the app"
untrustedWarning:
type: boolean
description: "Show a warning that the app is untrusted"
showOnWebpage:
type: boolean
description: "Show the App on the Startpage of the Webpage"
stopAutoRedirect:
type: boolean
description: "User alwasy have to click at the oAuth-Accept page to get redirect"
hideInAppList:
type: boolean
description: "User don't see this App in his App list"
userCantRemoveApp:
type: boolean
description: "User can't revoe access to this App in his App list"
access:
type: object
properties:
oAuth:
type: boolean
description: "App can use oAuth to autorize user"
api:
type: boolean
description: "App can make API Calls"
update_apps:
type: boolean
description: "App can make Updates to the users app (if the user is developer)"
update_profile:
type: boolean
description: "App can update the Users Profile"
update_access:
type: boolean
description: "App can revoke users Access to other Apps"
read_access:
type: boolean
description: "App can read users information from the api (Currently unimportend)"
read_apps:
type: boolean
description: "App can get a list of the users apps"
read_profile:
type: boolean
description: "App can read the profile from the user"
App:
type: "object"
properties:
id:
type: integer
description: "ID of the APP"
example: 42
name:
type: string
description: "Name of the App"
example: "Gitea"
description:
type: string
description: "Description of the App"
example: "Self-hostet Git server for our organisation"
url:
type: string
description: "URL of the Webpage of the App"
example: "https://git.keks.cloud"
directUrl:
type: string
description: "Link to log the user in the App, if the user is alweady give access to the App this link should rederect the user direct to the Dashboard"
example: "https://git.keks.cloud/user/oauth2/KeksAccount"
properties:
type: object
properties:
testingWarning:
type: boolean
description: "Show a warning at the App-Page that the App is in Testing-Modus"
autoAccept:
type: boolean
description: "User don't have to accept to go to the app, if user is at the oAuth-Accept page he will direct redirect to the app"
untrustedWarning:
type: boolean
description: "Show a warning that the app is untrusted"
showOnWebpage:
type: boolean
description: "Show the App on the Startpage of the Webpage"
stopAutoRedirect:
type: boolean
description: "User alwasy have to click at the oAuth-Accept page to get redirect"
hideInAppList:
type: boolean
description: "User don't see this App in his App list"
userCantRemoveApp:
type: boolean
description: "User can't revoe access to this App in his App list"
access:
type: object
properties:
oAuth:
type: boolean
description: "App can use oAuth to autorize user"
api:
type: boolean
description: "App can make API Calls"
update_apps:
type: boolean
description: "App can make Updates to the users app (if the user is developer)"
update_profile:
type: boolean
description: "App can update the Users Profile"
update_access:
type: boolean
description: "App can revoke users Access to other Apps"
read_access:
type: boolean
description: "App can read users information from the api (Currently unimportend)"
read_apps:
type: boolean
description: "App can get a list of the users apps"
read_profile:
type: boolean
description: "App can read the profile from the user"
AppAccess:
type: object
properties:
app_id:
type: integer
description: ID of the App
user_id:
type: integer
description: ID of the User
status:
type: string
enum:
- "created"
- "allowed"
- "disabled"