To access the rokka API, you need an user and a membership of that user to the organization you want to access. This is automatically done, when you create a new account in the signup screen or with the corresponding API call.
Each user has one or several Api-Keys, can belong to different organizations and can have different access level on each of those organisations. You can have up to 5 different Api-Keys per user. Useful if you want to change an Api-Key via key rotation, or you just want to use different ones in different places. See below for details.
Each user object has also an unique id, this should be used to add a user to a different organization with the membership calls explained below.
It's a good idea to create a user for your application with only write access (and not admin rights) when you start using the service in earnest.
You can easily add new users with different membership rights in the dashboard.
| Attribute | Description |
|---|---|
| id | UUID, doesn't change |
| Email address of this user |
Signing up is done using the /users endpoint. A post will do the trick. Try it out
This is the only route besides the operations listing, where you don't need authorization. Everything else will need it, so check for the authorization part of the guide to see the details.
curl -H 'Content-Type: application/json' -X POST 'https://api.rokka.io/users' -d '[
{
"email": "my@example.org",
"organization": "example-organization"
}
]'
$client = \Rokka\Client\Factory::getUserClient();
$user = $client->createUser('my.email@example.org');
echo "Api-Key: " . $user->getApiKey() . PHP_EOL;
You get back a full user object, containing your Api-Key. To be safe, this information is also sent by email to your address. Save these, you need them for authentication. The Api-Key can't be recovered later, so make sure, you keep it safe somewhere.
You can get the user_id of the logged in user with the /user endpoint. Try it out
For security and privacy reasons, we currently only return the user_id and not other information. The reason is that there are valid reasons for using the Api-Key in a public setting (for uploading or reading) and therefore people could access your email adress then.
curl 'https://api.rokka.io/user'
Response:
{
"user_id": "271cce77-45c7-4f6d-a0f6-a4edc29964e6"
}
$client = \Rokka\Client\Factory::getUserClient('awesomecompany', 'apiKey');
$user_id = $client->getCurrentUserId();
var_dump($user_id);
If you need a new user, either for example for different roles (a write user) or you need a new Api-Key, you can do that in one call. Try it out
It's best practice to create a user with only write access for general operations, and only use the admin user when necessary.
You can also to this directly in the dashboard.
curl -X POST "https://api.rokka.io/organizations/awesomecompany/memberships" -H "Content-Type: application/json" -d '{
"roles": [ "write" ]
}'
It will return a new user object with a membership to the current organisation, with a new user_id, Api-Key and the roles defined. Again, keep that Api-Key somewhere safe, you can't recover it (but you could just reissue this command again to get a new one)
{
"email": "test@example.org",
"user_id": "ccd7be95-5db2-4e83-994d-f3269a98578b",
"api_key": "kim8ZlrzJWEogDlqhOsN3daS8I4ajZom",
"organization_id": "251581fc-12ba-466b-bb21-34d23838dc83",
"roles": [
"write"
]
}
use \Rokka\Client\Core\Membership;
$client = \Rokka\Client\Factory::getUserClient('awesomecompany', 'apiKey');
$membership = $client->createUserAndMembership([Membership::ROLE_READ]);
var_dump($membership);
Membership is the connection between a user and an organization. It defines their access rights to that organization as well.
You can organize the memberships of an organization directly in the dashboard.
Or with the API calls mentioned here.
| Attribute | Description |
|---|---|
| The email of the user | |
| user_id | UUID of user |
| organization_id | UUID of organization |
| roles | Which roles the user has for this organization as array |
List all memberships associated to this organisation. Try it out
curl -X GET 'https://api.rokka.io/organizations/awesomecompany/memberships'
This returns something like
{
"total": 2,
"items": [
{
"email": "test@example.org",
"user_id": "271cce77-45c7-4f6d-a0f6-a4edc29964e6",
"organization_id": "251581fc-12ba-466b-bb21-34d23838dc83",
"roles": [
"admin"
],
"active": true,
"last_access": "2018-10-22T16:06:36+02:00"
},
{
"email": "else@example.org",
"user_id": "c8791715-a873-475e-96b2-5ffd488112e7",
"organization_id": "251581fc-12ba-466b-bb21-34d23838dc83",
"roles": [
"upload",
"read"
],
"active": true
}
]
}
$client = \Rokka\Client\Factory::getUserClient('awesomecompany', 'apiKey');
$memberships = $client->listMemberships();
var_dump($memberships);
If you have admin rights (given when creating a new organization automatically), you can add a user to the organization with this call. Try it out
awesomecompany would be your organization name, userId the id of the to be added user. (You can get the user_id with a GET /user call, if you know the Api-Key of that user)
Role can be read, write, upload, sourceimages:read, sourceimages:download:protected, sourceimages:write, sourceimages:unlock,admin.
sourceimages:read or sourceimages:write.sourceimages:read and sourceimages:write can't download the original binaries, when they are from
protected images. You have to explicitly give the sourceimages:download:protected role then. Other roles
can download them.sourceimages:unlock can only lock and unlock sourceimages and nothing else, best to be combined with another role.If you want for example assign an existing user with just a read role to your organization, do the following
curl -H 'Content-Type: application/json' -X PUT 'https://api.rokka.io/organizations/awesomecompany/memberships/c8791715-a873-475e-96b2-5ffd488112e7' -d '{
"roles": ["read"]
}'
use \Rokka\Client\Core\Membership;
$client = \Rokka\Client\Factory::getUserClient('awesomecompany', 'apiKey');
$membership = $client->createMembership('c8791715-a873-475e-96b2-5ffd488112e7', [Membership::ROLE_READ]);
var_dump($membership);
If the membership didn't exist yet, it will return a 201 code. If the membership existed and has been updated, it will return a 200 code. If the membership existed and it has not been updated, it will return a 204 code. In a special case, if the action would remove the last active admin from the organization, it will return a 409 error and not execute the removal. This is to prevent locking yourself out of the organization. The only way to remove this is to delete the organization as a whole.
To remove a member from an organization, send a DELETE request with the user_id in it. Try it out
curl -H -X DELETE 'https://api.rokka.io/organizations/awesomecompany/memberships/c8791715-a873-475e-96b2-5ffd488112e7'
$client = \Rokka\Client\Factory::getUserClient('awesomecompany', 'apiKey');
$client->deleteMembership('c8791715-a873-475e-96b2-5ffd488112e7');
If the user is removed from the organization, it will return a 204 code. If the user is not found or not a member of this organization, it will return a 404 code. If the specified user is the only admin of this organization, it will return a 409 code. The last admin of an organization can not be removed
A common usecase is to rotate/change your Api key from time to time (or if your key leaked somehow).
There are two ways to rotate an Api key. Either directly on the User or you create a new User and add it to an organization via a membership.
The easiest way to manage your Api Keys is via the Dashboard at https://rokka.io/dashboard/#/apikeys.
In general, if a user has read, upload or sourceimages:read rights somewhere, all this methods won't work.
We assume, that such a user is used for public use and people could otherwise just change your key, if they
know the Api Key. If you want to change an Api Key of such a user, you should use the 2nd method with creating
a new user and associating it to an organization.
You can have up to 5 Api Keys per user. To add a new one, you POST to the /user/apikeys endpoint. It can have an
optional comment, too. Try it out
curl -X POST "https://api.rokka.io/user/apikeys" -H "Content-Type: application/json" -d '{
"comment": [ "some comment" ]
}'
PHP:
$client = \Rokka\Client\Factory::getUserClient('awesomecompany', 'apiKey');
$userApiKey = $client->addUserApiKey('some comment');
echo $userApiKey->getApiKey();
JavaScript:
const userApiKey = (await rokka.user.addApiKey('foo')).body
console.log(userApiKey.api_key);
You'll get back an object, which contains the new Api Key. Store that somewhere safe, you or us can't get it later.
You can get all Api Keys (except the actual key, of course, just the info about it) with either
curl -X GET "https://api.rokka.io/user" -H "Content-Type: application/json"
or
curl -X GET "https://api.rokka.io/user/apikeys" -H "Content-Type: application/json"
You can delete an existing Api Key with a delete request on /user/apikeys/$ApiKeyId. You can't delete the
currently used key. Try it out.
curl -X DELETE "https://api.rokka.io/user/apikeys/$ApiKeyId" -H "Content-Type: application/json"
PHP:
$client = \Rokka\Client\Factory::getUserClient('awesomecompany', 'apiKey');
$userApiKey = $client->deleteUserApiKey($id);
Javascript:
rokka.user.deleteApiKey(id)
If you don't remember, which Api Key ID the currently used Api Key has, you can do the following request. Try it out.
curl -X GET "https://api.rokka.io/user/apikeys/current" -H "Content-Type: application/json"
PHP:
$client = \Rokka\Client\Factory::getUserClient('awesomecompany', 'apiKey');
echo $client->getCurrentUserApiKey()->getId();
Javascript:
console.log((await rokka.user.getCurrentApiKey()).body)
If you want to delete all Api Keys, except the currently used one, you can use the following code. Since you can't delete the currently used Api Key, we have to check for that and not try to delete that one.
PHP:
$client = \Rokka\Client\Factory::getUserClient('awesomecompany', 'apiKey');
$user = $client->getCurrentUser();
$current = $client->getCurrentUserApiKey()->getId();
foreach ($user->getApiKeys() as $apiKey) {
$id = $apiKey->getId();
if ($current->getId() !== $id) {
echo("Delete $id\n");
$userClient->deleteUserApiKey($apiKey->getId());
}
}
JavaScript:
const currentKey = (await rokka.user.getCurrentApiKey()).body
const apiKeys = (await rokka.user.listApiKeys()).body
for (let key of apiKeys) {
if (key.id !== currentKey.id) {
console.log(`Delete ${key.id}`)
await rokka.user.deleteApiKey(key.id)
}
}
The other option to get a new Api Key is to create a new user and add it to an organization. You can do this in one call.
You create a new user with a membership association to the current organization with the same permissions as the one with old key.
curl -X POST "https://api.rokka.io/organizations/awesomecompany/memberships" -H "Content-Type: application/json" -d '{
"roles": [ "write" ]
}'
Then copy the api_key returned here and change all your keys with it in your applications. When done and deployed, you can remove the old user from this organization with its user_id.
curl -X DELETE 'https://api.rokka.io/organizations/awesomecompany/memberships/c8791715-a873-475e-96b2-5ffd488112e7'
You can get the user_id with the following command, in case you don't have it at hand anymore (while using the old Api-Key for authorization):
curl -X GET 'https://api.rokka.io/user' -H "Content-Type: application/json"
See the Authentication guide for details about how to get expiring JWT tokens for authentication.