(only supported verbs are shown for each endpoint)
Contents
GET
/global/users
¶Returns terse list of users
Example request:
$ curl -XGET '/global/users'
Example response
{
"users": [
"admin",
"robert",
"mary",
"john"
]
}
GET
/global/users/
(string: username)¶Get a user and create and return an auth token (if necessary). This will create a new auth token if one does not currently exist.
This can be considered the equivalent to “logging in”.
Parameters: |
|
---|
Example request
$ curl -XGET '/global/users/joe?password=1234'
Example response
{
"status": "ok",
"message": {
"username": "joe",
"attributes": {},
"auth_token": [
"NWFjNzkwNWQ4MjQyNzY5MWJjMjVlOTE4ODMwM2E1M2EyMzBiZDIyMFjNzkwNWQ4MjQyNzY5MWJjMjVlOTE4ODMQ"
],
"permissions": {
"apps": {
"*": "read/write",
"_global": "read/write"
},
"actions": {
"*": {
"*": "execute"
}
},
"servers": "*"
}
}
}
GET
/global/users/
(string: username)/permissions
¶Get all current applications, actions and servers the user has permissions to access, computed according to the permissions object associated with the user.
Example request
$ curl -XGET '/global/users/joe/permissions'
Example response
{
"username": "joe",
"applications": {
"read/write": [
"widgetmaker",
"widget2"
],
"read": [
"_global"
]
},
"actions": {
"widgetmaker": [
"ExampleAction",
"SpecialDeploymentAction",
"CleanupBuilds"
]
},
"servers": [
"server01",
"server02"
]
}
PUT
/global/users
¶Creates a new user or modifies an existing user.
Parameters: |
|
---|---|
JSON Parameters: | |
|
Permissions JSON object
The permissions JSON object consists of three name/value pairs: apps, actions, servers.
The “apps” value consists of one subobject with an arbitrary number of name/value pairs. The name is treated as a glob pattern matching against application names. The value is the permissions to grant applications which match the pattern. Valid permissions are “read” and “write” (delimited with ‘/’ for both). Note that order is not significant (“read/write” is the same as “write/read”) and the ‘/’ delimiter is simple convention. Only the existence of “read” and “write” substrings are checked, so “read;write” would work equally well.
Note
There exists a special application named ‘_global’. This represents access to all administrative containers/endpoints including nearly everythign under /global (with the exception of individual user objects, which can be accessed by simple password auth, and tokens which are permissionless) as well as the jobs container (but not individual jobs).
“read” allows access to the GET verb for all endpoints associated with that application while “write” allows access to all verbs which change state (PUT, POST, PATCH, DELETE).
The “actions” value contains an object with an arbitrary number of nested subobjects, each treated as a glob pattern matching application names. The value associated with any pattern is a subobject with the names treated as glob patterns matching action names of that application. Finally, the value associated with the action glob is tested for the substring “execute”. If it exists, permission is granted to execute that action. If it does not, permission is denied. Execute permission allows access to all verbs for that action.
Note
Conflicting permissions statements have undefined behavior (it depends upon the order of evaluation which is not guaranteed).
The “servers” value consists of a simple list of glob patterns which match server names. The user will be granted full permission to any servers matching any of the patterns.
Example request
$ curl -XPUT '/global/users?username=joe&password=1234' -d '
{
"attributes": {
"address": "123 Spring Street, Knoxville, TN 012345"
},
"permissions": {
"apps": {
"*": "read/write",
"newapp": ""
},
"actions" {
"newapp": {
"ScriptedAction": "execute"
},
"otherapp": {
"*": "execute"
}
},
"servers": []
}
}'
This grants the following permissions:
PATCH
/global/users/
(string: username)¶Modify a user. On the fields specified in the JSON body (or JSON Patch) will be altered.
Parameters: |
|
---|---|
JSON Parameters: | |
|
Password may be changed via either JSON body or JSON Patch methods. Note that for JSON Patch password changes, only the “replace” operation is supported.
Example request
$ curl -XPATCH '/global/users/joe?password=1234' -d '{ "attributes": { "nickname": "joey" } }'
Example response
{
"status": "ok",
"message": {
"username": "joe",
"attributes": {
"nickname": "joey"
},
"auth_token": [
"NWFjNzkwNWQ4MjQyNzY5MWJjMjVlOTE4ODMwM2E1M2EyMzBiZDIyMFjNzkwNWQ4MjQyNzY5MWJjMjVlOTE4ODMQ"
],
"permissions": {
"apps": {
"*": "read/write",
"_global": "read/write"
},
"actions": {
"*": {
"*": "execute"
}
},
"servers": ["*"]
}
}
}
DELETE
/global/users/
(string: username)¶Delete a user.
Note
You can use either password authentication or auth token.
Parameters: |
|
---|
Example request
$ curl -XDELETE '/global/users/joe'
GET
/global/tokens
¶Get list of issued auth tokens. This requires ‘_global’ permissions to view.
Example request
$ curl -XGET '/global/tokens'
GET
/global/tokens/
(string: token)¶Get information about token (associated user and time of issuance).
Note
This endpoint does not require authentication. The token is the secret.
Example request
$ curl -XGET
'/global/tokens/NWFoNzkwNWQ4M2QyNzY5MWJjMjVlJdu7ODMwM2E1M2EyMzBiZDIyMmMyMGE9Idjn4Yzg2ZjYwODQ1ZWYyNTVmM9'
DELETE
/global/tokens/
(string: token)¶Delete an auth token. This is the equivalent of “logging out”.
Note
This endpoint does not require authentication. The token is the secret.
Example request
$ curl -XDELETE
'/global/tokens/NWFoNzkwNWQ4M2QyNzY5MWJjMjVlJdu7ODMwM2E1M2EyMzBiZDIyMmMyMGE9Idjn4Yzg2ZjYwODQ1ZWYyNTVmM9'
GET
/global/gitproviders
¶Get list of gitproviders.
Example request
$ curl -XGET '/global/gitproviders'
GET
/global/gitproviders/
(string: gitprovider)¶Get information about a gitprovider.
Example request
$ curl -XGET '/global/gitproviders/mygitprovider'
PUT
/global/gitproviders
¶Parameters: |
|
---|---|
JSON Parameters: | |
|
Create new gitprovider.
Example JSON body
{
"type": "bitbucket",
"auth": {
"username": "my-username",
"password": "password1234"
}
}
Example request
$ curl -H "Content-Type: application/json" -XPUT '/global/gitproviders?name=mygitprovider' -d '{
"type": "bitbucket",
"auth": {
"username": "my-username",
"password": "password1234"
}
}'
PATCH
/global/gitproviders/
(string: gitprovider)¶JSON Parameters: | |
---|---|
|
Modify gitprovider. Only fields provided in JSON body will be changed.
Note
The only valid field to modify is “auth”.
Example request
$ curl -XPATCH '/global/gitproviders/mygitprovider' -d '{ "auth": {
"username": "my-username",
"password": "password1234"
}
}'
DELETE
/global/gitproviders/
(string: gitprovider)¶Remove gitprovider.
Example request
$ curl -XGET '/global/gitproviders/mygitprovider'
GET
/global/keypairs
¶Get list of keypairs.
Example request
$ curl -XGET '/global/keypairs'
GET
/global/keypairs/
(string: keypair)¶Get information about a keypair.
Example request
$ curl -XGET '/global/keypairs/mykeypair'
Keypairs can be uploaded either as JSON-encoded strings (PUT request) or as files (POST request).
PUT
/global/keypairs
¶Parameters: |
|
---|---|
JSON Parameters: | |
|
Create new keypair by providing JSON-formatted keys or by uploading key files directly. Both keys must be in SSH format. Use the URL parameter “from” to indicate which request is being made: “json” means the key data is JSON-encoded within the request body, “files” means the key files are provided as POST file data.
Example JSON body
Note
Key data omitted from examples.
{
"private_key": "-----BEGIN RSA PRIVATE KEY-----\\n...\\n-----END RSA PRIVATE KEY-----\\n",
"public_key": "ssh-rsa ... foo@bar.com\\n"
}
Example request (JSON-encoded keys)
$ curl -H "Content-Type: application/json" -XPUT '/global/keypairs?type=git&name=mykeypair&from=json' -d '{
"private_key": "-----BEGIN RSA PRIVATE KEY-----\\n...\\n-----END RSA PRIVATE KEY-----\\n",
"public_key": "ssh-rsa ... foo@bar.com\\n"
}'
Example request (key files)
$ curl -XPOST '/global/keypairs?type=git&name=mykeypair&from=files' -F "private_key=@/path/to/private.key"
-F "public_key=@/path/to/public.key"
POST
/global/keypairs
¶Parameters: |
|
---|---|
Form Parameters: | |
|
Create new keypair by uploading key files.
Example request
$ curl -XPOST '/global/keypairs?type=git&name=mykeypair&from=files' -F "private_key=@/home/user/keys/mykey"
-F "public_key=@/home/user/keys/mykey.pub"
PATCH
/global/keypairs/
(string: keypair)¶JSON Parameters: | |
---|---|
|
Modify keypair by replacing keys. Only keys provided in JSON body will be changed, but you will almost always want to specify both.
Example request
$ curl -XPATCH '/global/keypairs/mykeypair' -d '{
"private_key": "-----BEGIN RSA PRIVATE KEY-----\\n...\\n-----END RSA PRIVATE KEY-----\\n",
"public_key": "ssh-rsa ... foo@bar.com\\n"
}'
DELETE
/global/keypairs/
(string: keypair)¶Remove keypair.
Example request
$ curl -XDELETE '/global/keypair/mykeypair'