Organization

Creates an API key for the authenticated service provider.

Requires the Organization:write scope; keys issued with the older ServiceProvider:write keep working. The new key’s scopes must also be a subset of the calling key’s own, so a key can never create one more powerful than itself. Asking for a scope the caller does not hold is rejected and names the scope.

Each requested scope is an explicit "Module:verb"; a bare module name is rejected. The key value comes back on this response and on no other - only its hash is stored. The new key records the key that created it, returned as ParentApiKeyId by GET /v1/api-keys.

POST

api-keys

curl --request POST \
  --url https://api.usw.gorelo.io/v1/api-keys \
  --header 'Content-Type: application/json-patch+json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "Name": "CI pipeline",
  "Description": "<string>",
  "Scopes": [
    "Tickets:read",
    "Tickets:write"
  ]
}
'

import requests

url = "https://api.usw.gorelo.io/v1/api-keys"

payload = {
    "Name": "CI pipeline",
    "Description": "<string>",
    "Scopes": ["Tickets:read", "Tickets:write"]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json-patch+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    Name: 'CI pipeline',
    Description: '<string>',
    Scopes: ['Tickets:read', 'Tickets:write']
  })
};

fetch('https://api.usw.gorelo.io/v1/api-keys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usw.gorelo.io/v1/api-keys",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'Name' => 'CI pipeline',
    'Description' => '<string>',
    'Scopes' => [
        'Tickets:read',
        'Tickets:write'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json-patch+json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usw.gorelo.io/v1/api-keys"

	payload := strings.NewReader("{\n  \"Name\": \"CI pipeline\",\n  \"Description\": \"<string>\",\n  \"Scopes\": [\n    \"Tickets:read\",\n    \"Tickets:write\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usw.gorelo.io/v1/api-keys")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"Name\": \"CI pipeline\",\n  \"Description\": \"<string>\",\n  \"Scopes\": [\n    \"Tickets:read\",\n    \"Tickets:write\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usw.gorelo.io/v1/api-keys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json-patch+json'
request.body = "{\n  \"Name\": \"CI pipeline\",\n  \"Description\": \"<string>\",\n  \"Scopes\": [\n    \"Tickets:read\",\n    \"Tickets:write\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": {
    "Id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "KeyValue": "<string>",
    "Name": "<string>",
    "Description": "<string>",
    "Scopes": [
      "<string>"
    ],
    "CreatedAt": "2023-11-07T05:31:56Z"
  },
  "DataContext": null,
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

Authorizations

X-API-Key

string

header

required

Your Gorelo API key. See Generate API key. If your data is hosted in Australia, click the base URL at the top of this page and select https://api.aue.gorelo.io.

Body

Request body for creating an API key. The owning service provider and the calling key's own scopes are resolved from the request context, not from the body.

Name

string

A name to identify the key by. Required.

Example:

"CI pipeline"

Description

string | null

What the key is for.

Scopes

enum<string>[]

The scopes the new key carries, each an explicit "Module:verb". Required, and every entry must be one the calling key already holds.

The valid values are published as the enum on this property. Verbs are independent - write does not imply read. Note Project is singular. Scopes are stored as published here, whatever casing is sent; the older ServiceProvider:verb is still accepted and is stored as Organization:verb.

Available options:

Organization:read,

Organization:write,

Organization:delete,

Tickets:read,

Tickets:write,

Tickets:delete,

Clients:read,

Clients:write,

Clients:delete,

Contacts:read,

Contacts:write,

Contacts:delete,

Billing:read,

Billing:write,

Billing:delete,

Project:read,

Project:write,

Project:delete,

Assets:read,

Assets:write,

Assets:delete,

Alerts:read,

Alerts:write,

Alerts:delete,

Forms:read,

Forms:write,

Forms:delete,

Documents:read,

Documents:write,

Documents:delete

Example:

["Tickets:read", "Tickets:write"]

Response

StatusCode

enum<integer>

Available options:

100,

101,

102,

103,

200,

201,

202,

203,

204,

205,

206,

207,

208,

226,

300,

301,

302,

303,

304,

305,

306,

307,

308,

400,

401,

402,

403,

404,

405,

406,

407,

408,

409,

410,

411,

412,

413,

414,

415,

416,

417,

421,

422,

423,

424,

426,

428,

429,

431,

451,

500,

501,

502,

503,

504,

505,

506,

507,

508,

510,

511

IsSuccess

boolean

Data

object

The created key. KeyValue is returned here and nowhere else, ever.

Show child attributes

DataContext

object | null

Example:

null

Notifications

object[]

Show child attributes

⌘I

Creates an API key for the authenticated service provider.

curl --request POST \
  --url https://api.usw.gorelo.io/v1/api-keys \
  --header 'Content-Type: application/json-patch+json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "Name": "CI pipeline",
  "Description": "<string>",
  "Scopes": [
    "Tickets:read",
    "Tickets:write"
  ]
}
'

import requests

url = "https://api.usw.gorelo.io/v1/api-keys"

payload = {
    "Name": "CI pipeline",
    "Description": "<string>",
    "Scopes": ["Tickets:read", "Tickets:write"]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json-patch+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    Name: 'CI pipeline',
    Description: '<string>',
    Scopes: ['Tickets:read', 'Tickets:write']
  })
};

fetch('https://api.usw.gorelo.io/v1/api-keys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usw.gorelo.io/v1/api-keys",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'Name' => 'CI pipeline',
    'Description' => '<string>',
    'Scopes' => [
        'Tickets:read',
        'Tickets:write'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json-patch+json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usw.gorelo.io/v1/api-keys"

	payload := strings.NewReader("{\n  \"Name\": \"CI pipeline\",\n  \"Description\": \"<string>\",\n  \"Scopes\": [\n    \"Tickets:read\",\n    \"Tickets:write\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usw.gorelo.io/v1/api-keys")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"Name\": \"CI pipeline\",\n  \"Description\": \"<string>\",\n  \"Scopes\": [\n    \"Tickets:read\",\n    \"Tickets:write\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usw.gorelo.io/v1/api-keys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json-patch+json'
request.body = "{\n  \"Name\": \"CI pipeline\",\n  \"Description\": \"<string>\",\n  \"Scopes\": [\n    \"Tickets:read\",\n    \"Tickets:write\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": {
    "Id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "KeyValue": "<string>",
    "Name": "<string>",
    "Description": "<string>",
    "Scopes": [
      "<string>"
    ],
    "CreatedAt": "2023-11-07T05:31:56Z"
  },
  "DataContext": null,
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}