Knowledge base

Information about vpsFree.org, manuals and FAQs.

User Tools

Site Tools

You are here: Knowledge Base of vpsFree.org » manuals » vps » API
Trace:
manuals:vps:api

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Last revisionBoth sides next revision
manuals:vps:api [2019/05/17 14:03] – Aithermanuals:vps:api [2024/01/02 20:52] – Scopes aither
Line 8: Line 8:
 ===== API Documentation ===== ===== API Documentation =====
 The API documentation, i.e. a list of objects, possible actions as well as input and output The API documentation, i.e. a list of objects, possible actions as well as input and output
-parameters can be found at https://api.vpsfree.cz/v5.0/.+parameters can be found at https://api.vpsfree.cz/v6.0/.
  
 Even without logging in, you can see a list of all objects, i.e. even those that only Even without logging in, you can see a list of all objects, i.e. even those that only
Line 26: Line 26:
   * JavaScript - https://github.com/vpsfreecz/haveapi/tree/master/clients/js   * JavaScript - https://github.com/vpsfreecz/haveapi/tree/master/clients/js
   * Go - https://github.com/vpsfreecz/haveapi/tree/master/clients/go   * Go - https://github.com/vpsfreecz/haveapi/tree/master/clients/go
-  * The HaveAPI web interface - https://github.com/vpsfreecz/haveapi-webui +  * The HaveAPI web interface - https://github.com/vpsfreecz/haveapi-webui (outdated) 
-  * A file system based on FUSE - https://github.com/vpsfreecz/haveapi-fs+  * A file system based on FUSE - https://github.com/vpsfreecz/haveapi-fs (outdated)
  
 Usage examples can always be found in the ''README.md'' of each client. In general, the client Usage examples can always be found in the ''README.md'' of each client. In general, the client
Line 38: Line 38:
  
 ===== Authentication===== ===== Authentication=====
-There are two authentication methods available. The first and simpler one is HTTP +There are two authentication methods:
-basic. The name and password must be sent along with every API request. This is a good +
-choice for one-off actions. However, if you need to call the API several times or +
-automatically, storing the password on the disk or copying it constantly is not a good idea.+
  
-Another method is authentication using tokens. The way this method works is that +  * [[#http_basic|HTTP Basic]] 
-the client first requests a token to be created, one for which the client needs +  * [[#tokens|Using tokens]] 
-the name, password and possibly TOTP. As soon as the client receives the token, + 
-the name and password can be forgotten since it is the token that is then used +Example usage in different programming languages can be found in [[https://api.vpsfree.cz/v6.0/#auth|API documentation]]. 
-for further authentication.+ 
 +==== HTTP Basic ==== 
 + The name and password must be sent along with every API request in HTTP header //Authorization//. 
 +This is a good choice for one-off actions. However, if you need to call the API repeatedly or 
 +automatically, storing the password on the disk or entering it constantly is not a good idea. 
 +HTTP Basic cannot be used if two-factor authentication is enabled on your account. 
 + 
 +==== Tokens ==== 
 +The client first requests a token using your credentials and optionally also TOTP. 
 +As soon as the client receives the token, the credentials can be forgotten and the token 
 +is used for authentication.
  
 There can be several types of tokens with different lifetimes: There can be several types of tokens with different lifetimes:
  
-  * fixed - token validity is fixed +  * //fixed// - token validity is fixed 
-  * renewable_manual - token validity can be manually extended +  * //renewable_manual// - token validity can be manually extended 
-  * renewable_auto - token validity is extended after every request +  * //renewable_auto// - token validity is extended after every request 
-  * permament - the token is valid permanently, or until it is deleted+  * //permament// - the token is valid permanently, or until it is deleted
  
 The type of token and time period by which its validity is extended is chosen The type of token and time period by which its validity is extended is chosen
 by the client. by the client.
 +
 +===== Scopes =====
 +Authentication tokens can be restricted to selected actions. Each action has its own scope,
 +you can find the available scopes in the documentation. You can configure scopes when you're
 +requesting a new authentication token.
 +
 +Example scopes:
 +
 +  * ''all'' allow access to all actions, this is used by the web interface and it is the default scope
 +  *  an empty scope will allow access only to ''user#current'', which gives information about the current user; this is used for logins from Discourse and KB
 +  * ''vps#show'' allow access to action show on vps resource
 +  * ''vps#show:vps_id=123'' allow access to action show on a specific VPS
 +  * ''vps#*'' allow all actions on vps resource
 +  * ''vps#*:vps_id=123'' all actions on vps resource, but only with VPS ID 123
 +  * ''{vps,dataset}#{index,show}'' list and show info about VPS and datasets
 +
 +Scopes can contain globs for resource and action names. Action name is separated from resource name by a hash (''#''). Optional object IDs are separated from action name by a colon ('':'') and cannot contain globs. You can find a list of available scopes and their parameters in the [[https://api.vpsfree.cz/|documentation]]. Each token can have multiple scopes separated by spaces. At least one scope must match the called action in order for access to be granted.
  
 ===== CLI ===== ===== CLI =====
Line 288: Line 312:
         --user USER                  User name         --user USER                  User name
         --password PASSWORD          Password         --password PASSWORD          Password
 +        --scope [SCOPE]              Scope
         --token TOKEN                Token         --token TOKEN                Token
         --token-lifetime LIFETIME    Token lifetime, defaults to renewable_auto         --token-lifetime LIFETIME    Token lifetime, defaults to renewable_auto
Line 332: Line 357:
 access to ''~/.haveapi-client.yml'' can access and use the token. access to ''~/.haveapi-client.yml'' can access and use the token.
 </note> </note>
 +
 +Specify a scope:
 +
 +<code>
 +$ vpsfreectl --auth token --scope 'vps#*:vps_id=123' --save vps show 123
 +</code>
 +
 +The command above will ask for an authentication token that will only be allowed to call actions on the vps resource and only on VPS with ID 123.
  
 ==== Actions and Parameters ==== ==== Actions and Parameters ====
manuals/vps/api.txt · Last modified: 2024/01/02 21:05 by aither

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki