User - Roles

Base URL: https://your-domain.com

Admin endpoints for managing user roles and permissions. All endpoints require admin authentication.

Fetch All Roles

Retrieve all roles configured in the system.

Property	Value
Endpoint	Fetch All Roles
Method	`GET`
URL	`/api/v1/roles`
Authentication	Bearer Token

Request Headers:

Header	Value	Required
`Accept`	`application/json`	Yes
`Authorization`	`Bearer your-auth-token`	Yes

Query Parameters:

Parameter	Type	Required	Description
`isp_id`	integer	Yes	ISP ID
`branch_id`	integer	Yes	Branch ID
`user_id`	integer	Yes	User ID

Success Response (200 OK):

json

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Admin",
            "user_count": 2,
            "is_system": true
        },
        {
            "id": 2,
            "name": "Staff",
            "user_count": 10,
            "is_system": false
        }
    ]
}

Code Examples:

bash

curl -X GET "https://your-domain.com/api/v1/roles?isp_id=1&branch_id=1&user_id=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$response = $client->request('GET', '/api/v1/roles', [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
    'query' => [
        'isp_id'    => 1,
        'branch_id' => 1,
        'user_id'   => 1,
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const params = new URLSearchParams({
  isp_id: 1,
  branch_id: 1,
  user_id: 1,
});

const response = await fetch(`${BASE_URL}/api/v1/roles?${params}`, {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: `Bearer ${TOKEN}`,
  },
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"

response = requests.get(
    f"{BASE_URL}/api/v1/roles",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
    params={
        "isp_id": 1,
        "branch_id": 1,
        "user_id": 1,
    },
)

data = response.json()
print(data)

package main

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

const baseURL = "https://your-domain.com"
const token = "your-auth-token"

func main() {
	endpoint := baseURL + "/api/v1/roles"

	q := url.Values{}
	q.Set("isp_id", "1")
	q.Set("branch_id", "1")
	q.Set("user_id", "1")
	endpoint += "?" + q.Encode()

	req, _ := http.NewRequest("GET", endpoint, nil)
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;

const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();

    let response = client
        .get(format!("{BASE_URL}/api/v1/roles"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .query(&[
            ("isp_id", "1"),
            ("branch_id", "1"),
            ("user_id", "1"),
        ])
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

Fetch Role

Retrieve details of a specific role including permissions.

Property	Value
Endpoint	Fetch Role
Method	`GET`
URL	`/api/v1/roles/{id}`
Authentication	Bearer Token

Success Response (200 OK):

json

{
    "success": true,
    "data": {
        "id": 2,
        "name": "Staff",
        "permissions": [
            "subscribers.view",
            "subscribers.create",
            "packages.view"
        ],
        "user_count": 10
    }
}

Code Examples:

bash

curl -X GET "https://your-domain.com/api/v1/roles/1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$roleId = 1;

$response = $client->request('GET', "/api/v1/roles/{$roleId}", [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const roleId = 1;

const response = await fetch(`${BASE_URL}/api/v1/roles/${roleId}`, {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: `Bearer ${TOKEN}`,
  },
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"

role_id = 1

response = requests.get(
    f"{BASE_URL}/api/v1/roles/{role_id}",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
)

data = response.json()
print(data)

package main

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

const baseURL = "https://your-domain.com"
const token = "your-auth-token"

func main() {
	roleId := 1
	endpoint := baseURL + "/api/v1/roles/" + strconv.Itoa(roleId)

	req, _ := http.NewRequest("GET", endpoint, nil)
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;

const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();
    let role_id = 1;

    let response = client
        .get(format!("{BASE_URL}/api/v1/roles/{role_id}"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

Create Role

Create a new role with specified permissions.

Property	Value
Endpoint	Create Role
Method	`POST`
URL	`/api/v1/roles`
Authentication	Bearer Token

Request Body:

json

{
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 1,
    "name": "New Role",
    "permissions": ["subscribers.view", "packages.view"]
}

Parameter	Type	Required	Description
`name`	string	Yes	Role name
`permissions`	array	No	Array of permission keys

Success Response (201 Created):

json

{
    "success": true,
    "message": "Role created successfully",
    "data": {
        "id": 3
    }
}

Code Examples:

bash

curl -X POST "https://your-domain.com/api/v1/roles" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 1,
    "name": "New Role",
    "permissions": [
      "subscribers.view",
      "packages.view"
    ]
  }'

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$response = $client->request('POST', '/api/v1/roles', [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
    'json' => [
        'isp_id'      => 1,
        'branch_id'   => 1,
        'user_id'     => 1,
        'name'        => 'New Role',
        'permissions' => [
            'subscribers.view',
            'packages.view',
        ],
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const response = await fetch(`${BASE_URL}/api/v1/roles`, {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    Authorization: `Bearer ${TOKEN}`,
  },
  body: JSON.stringify({
    isp_id: 1,
    branch_id: 1,
    user_id: 1,
    name: 'New Role',
    permissions: [
      'subscribers.view',
      'packages.view',
    ],
  }),
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"

response = requests.post(
    f"{BASE_URL}/api/v1/roles",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
    json={
        "isp_id": 1,
        "branch_id": 1,
        "user_id": 1,
        "name": "New Role",
        "permissions": [
            "subscribers.view",
            "packages.view",
        ],
    },
)

data = response.json()
print(data)

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

const baseURL = "https://your-domain.com"
const token = "your-auth-token"

func main() {
	endpoint := baseURL + "/api/v1/roles"

	payload, _ := json.Marshal(map[string]any{
		"isp_id":      1,
		"branch_id":   1,
		"user_id":     1,
		"name":        "New Role",
		"permissions": []any{
			"subscribers.view",
			"packages.view",
		},
	})
	req, _ := http.NewRequest("POST", endpoint, bytes.NewBuffer(payload))
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;
use serde_json::json;

const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();

    let response = client
        .post(format!("{BASE_URL}/api/v1/roles"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .json(&json!({
            "isp_id": 1,
            "branch_id": 1,
            "user_id": 1,
            "name": "New Role",
            "permissions": [
                "subscribers.view",
                "packages.view"
            ]
        }))
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

Update Role

Update role name or permissions.

Property	Value
Endpoint	Update Role
Method	`PUT`
URL	`/api/v1/roles/{id}`
Authentication	Bearer Token

Request Body:

json

{
    "name": "Updated Role",
    "permissions": ["subscribers.view", "subscribers.create"]
}

Success Response (200 OK):

json

{
    "success": true,
    "message": "Role updated successfully"
}

Code Examples:

bash

curl -X PUT "https://your-domain.com/api/v1/roles/1" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "name": "Updated Role",
    "permissions": [
      "subscribers.view",
      "subscribers.create"
    ]
  }'

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$roleId = 1;

$response = $client->request('PUT', "/api/v1/roles/{$roleId}", [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
    'json' => [
        'name'        => 'Updated Role',
        'permissions' => [
            'subscribers.view',
            'subscribers.create',
        ],
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const roleId = 1;

const response = await fetch(`${BASE_URL}/api/v1/roles/${roleId}`, {
  method: 'PUT',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    Authorization: `Bearer ${TOKEN}`,
  },
  body: JSON.stringify({
    name: 'Updated Role',
    permissions: [
      'subscribers.view',
      'subscribers.create',
    ],
  }),
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"

role_id = 1

response = requests.put(
    f"{BASE_URL}/api/v1/roles/{role_id}",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
    json={
        "name": "Updated Role",
        "permissions": [
            "subscribers.view",
            "subscribers.create",
        ],
    },
)

data = response.json()
print(data)

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"strconv"
)

const baseURL = "https://your-domain.com"
const token = "your-auth-token"

func main() {
	roleId := 1
	endpoint := baseURL + "/api/v1/roles/" + strconv.Itoa(roleId)

	payload, _ := json.Marshal(map[string]any{
		"name":        "Updated Role",
		"permissions": []any{
			"subscribers.view",
			"subscribers.create",
		},
	})
	req, _ := http.NewRequest("PUT", endpoint, bytes.NewBuffer(payload))
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;
use serde_json::json;

const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();
    let role_id = 1;

    let response = client
        .put(format!("{BASE_URL}/api/v1/roles/{role_id}"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .json(&json!({
            "name": "Updated Role",
            "permissions": [
                "subscribers.view",
                "subscribers.create"
            ]
        }))
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

Delete Role

Delete a role from the system.

Property	Value
Endpoint	Delete Role
Method	`DELETE`
URL	`/api/v1/roles/{id}`
Authentication	Bearer Token

Success Response (200 OK):

json

{
    "success": true,
    "message": "Role deleted successfully"
}

Error Response (400 Bad Request):

json

{
    "success": false,
    "message": "Cannot delete role with assigned users"
}

Code Examples:

bash

curl -X DELETE "https://your-domain.com/api/v1/roles/1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$roleId = 1;

$response = $client->request('DELETE', "/api/v1/roles/{$roleId}", [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const roleId = 1;

const response = await fetch(`${BASE_URL}/api/v1/roles/${roleId}`, {
  method: 'DELETE',
  headers: {
    Accept: 'application/json',
    Authorization: `Bearer ${TOKEN}`,
  },
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"

role_id = 1

response = requests.delete(
    f"{BASE_URL}/api/v1/roles/{role_id}",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
)

data = response.json()
print(data)

package main

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

const baseURL = "https://your-domain.com"
const token = "your-auth-token"

func main() {
	roleId := 1
	endpoint := baseURL + "/api/v1/roles/" + strconv.Itoa(roleId)

	req, _ := http.NewRequest("DELETE", endpoint, nil)
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;

const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();
    let role_id = 1;

    let response = client
        .delete(format!("{BASE_URL}/api/v1/roles/{role_id}"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

Copy Role

Create a copy of an existing role with a new name.

Property	Value
Endpoint	Copy Role
Method	`POST`
URL	`/api/v1/roles/{id}/copy`
Authentication	Bearer Token

Request Body:

json

{
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 1,
    "name": "Copied Role"
}

Success Response (201 Created):

json

{
    "success": true,
    "message": "Role copied successfully",
    "data": {
        "id": 4
    }
}

Code Examples:

bash

curl -X POST "https://your-domain.com/api/v1/roles/1/copy" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 1,
    "name": "Copied Role"
  }'

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$roleId = 1;

$response = $client->request('POST', "/api/v1/roles/{$roleId}/copy", [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
    'json' => [
        'isp_id'    => 1,
        'branch_id' => 1,
        'user_id'   => 1,
        'name'      => 'Copied Role',
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const roleId = 1;

const response = await fetch(`${BASE_URL}/api/v1/roles/${roleId}/copy`, {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    Authorization: `Bearer ${TOKEN}`,
  },
  body: JSON.stringify({
    isp_id: 1,
    branch_id: 1,
    user_id: 1,
    name: 'Copied Role',
  }),
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"

role_id = 1

response = requests.post(
    f"{BASE_URL}/api/v1/roles/{role_id}/copy",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
    json={
        "isp_id": 1,
        "branch_id": 1,
        "user_id": 1,
        "name": "Copied Role",
    },
)

data = response.json()
print(data)

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"strconv"
)

const baseURL = "https://your-domain.com"
const token = "your-auth-token"

func main() {
	roleId := 1
	endpoint := baseURL + "/api/v1/roles/" + strconv.Itoa(roleId) + "/copy"

	payload, _ := json.Marshal(map[string]any{
		"isp_id":    1,
		"branch_id": 1,
		"user_id":   1,
		"name":      "Copied Role",
	})
	req, _ := http.NewRequest("POST", endpoint, bytes.NewBuffer(payload))
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;
use serde_json::json;

const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();
    let role_id = 1;

    let response = client
        .post(format!("{BASE_URL}/api/v1/roles/{role_id}/copy"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .json(&json!({
            "isp_id": 1,
            "branch_id": 1,
            "user_id": 1,
            "name": "Copied Role"
        }))
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

User - Roles ​

Fetch All Roles ​

Fetch Role ​

Create Role ​

Update Role ​

Delete Role ​

Copy Role ​

User - Roles

Fetch All Roles

Fetch Role

Create Role

Update Role

Delete Role

Copy Role