Permissions

The Akiles permission system controls who can access which gadgets (doors, lights, etc.) and when. It’s built around a flexible hierarchy that allows fine-grained access control for different scenarios like hotels, apartment rentals, office buildings, or co-working spaces.

Core concepts

    graph TD
    Site[Site] --> Gadget[Gadget]
    
    Member[Member] --> MGA
    MGA --> MemberGroup
    
    Member --> Email[Email]
    Member --> MagicLink[Magic Link]
    Member --> PIN[PIN]
    Member --> Card[NFC Card]
    Member --> Token[Member Token]
    
    subgraph Member
        MemberTime[starts_at, ends_at]
    end
    
    subgraph MGA[Member Group Association]
        MGATime[starts_at, ends_at]
    end
    
    subgraph MemberGroup[Member Group]
        PermRule
        subgraph PermRule[Permission Rules]
            Restrictions[Restrictions]
        end
    end
    
    subgraph Gadget
        Actions[Actions]
    end
    
    PermRule -.-> Site
    PermRule -.-> Gadget
    PermRule -.-> Actions
    
    Restrictions -.-> Schedule
    
    subgraph "Credentials"
        Email
        MagicLink
        PIN
        Card
        Token
    end
    
    classDef physical fill:#e1f5fe
    classDef permission fill:#f3e5f5
    classDef access fill:#e8f5e8
    classDef user fill:#fff3e0
    classDef restrictions fill:#fff9c4
    
    class Site,Gadget,Actions physical
    class MemberGroup,PermRule,MGA,Schedule permission
    class Email,MagicLink,PIN,Card,Token access
    class Member user
    class MemberTime,MGATime,Restrictions restrictions

Sites

A site is a physical location where Akiles devices are installed (e.g., a building, floor, or property). Sites contain gadgets and help organize the devices geographically.

Gadget

A gadget is something a member can interact with, for example a door, a light, an elevator, a locker. The permission system’s job is to decide which gadgets a given member can use.

Gadgets can have multiple actions, in which case permissions can be controlled per-action. For example a member can be allowed to lock a door but not unlock it.

Members

A member represents a person who needs access to your site. Each member has:

• One or more credentials (email, PIN, NFC card, etc.)
• Optional validity period (starts_at / ends_at) - when the member’s access is active

Member group associations

A member_group_association links a member to a member group. They have:

• Optional validity period (starts_at / ends_at) - when the association is active

Member groups

A member_group defines a set of permissions for accessing specific gadgets. Groups have:

• Permission rules that specify which gadgets the group can access. Each rule has:
  • Target: which gadgets does it give permission for. It can target:
    • All gadgets in the org.
    • All gadgets in a site.
    • One particular gadget, all actions.
    • One particular gadget, one particular action.
  • Restrictions
    • Schedule (e.g. Mon-Fri 9AM-6PM)
    • Presence check (use phone’s GPS to check the member is not too far away)
    • Applicable access methods.

Permission calculation

A member can access a gadget if:

1. Member is not deleted, and
2. Current datetime is inside member’s validity period (if set), and
3. The member has an association with a member group, and
4. Current datetime is inside member’s validity period (if set), and
5. The member group has a permission rule that:
   • matches the gadget
   • matches the gadget’s action
   • all restrictions pass:
     • if presence check is enabled, the member must be opening with an access method that requires physical presence (Bluetooth, NFC, PIN), or is opening via internet but the phone’s GPS confirms they’re close.
     • if a schedule is set, current time is within it.
     • if access method list is set, the member is using an allowed access method.

To summarize:

• Member group associations are ORed. A member’s permissions are the sum of all group associations.
• Member group permission rules are ORed. A group’s permissions are the sum of all rules.
• Validity periods and restrictions are ANDed. The time a member can access is the intersection of the member’s validity period, the member group association’s validity period, and the schedule.

For debugging, you can view the result of this calculation in the admin panel:

• In “Member -> Calculated permissions” you can see all gadgets the member can access.
• In “Device -> Calculated permissions” you can see all members that can access the device’s gadgets.

You can also log in to the app or webapp as the member (using email or magic link) to see what the member has access to. Note the app lists all gadgets the user has some access to, the validity periods and restrictions are checked when you actually try to use the gadget.

Credentials

Members can authenticate and gain access through several credential types:

Email

• Use case: General-purpose access via web or mobile app
• How it works: User logs into https://web.akiles.app or the Akiles mobile app with their email
• Pros: Works on web and mobile app. Member can do actions via internet, Bluetooth or virtual NFC card.
• Cons: Requires user to login
• API: Use POST /members/{member_id}/emails

Magic Links

• Use case: One-click access without registration
• How it works: User clicks a unique link to access controls directly
• Pros: No registration or login required, works on web and mobile app. Member can do actions via internet, Bluetooth or virtual NFC card.
• Cons: Links must be securely transmitted to users
• API: Use POST /members/{member_id}/magic_links

PINs

• Use case: Physical access via device keypad
• How it works: User enters PIN directly on the Akiles device
• Pros: No phone/internet required
• Cons: Limited to physical device access. Less secure, you can watch someone enter their PIN.
• API: Use POST /members/{member_id}/pins

NFC Cards

• Use case: Traditional card-based access
• How it works: User taps physical NFC card on Akiles device
• Pros: Fast, familiar, works offline. Very secure, Akiles cards can’t be cloned.
• Cons: Requires physical card distribution
• API: Use POST /members/{member_id}/cards

Member Tokens

• Use case: For use with the Akiles SDK.
• How it works: You write your own mobile app. You have total control of registration, login, access flow UX.
• API: Use POST /members/{member_id}/tokens

All credentials bound to a member have the same permissions. If you want to give a person both PIN and card access, we recommend you create a single member and attach the two credentials to it. The event logs contain info on which member and which credential was used to access, you don’t need multiple members to distinguish credentials.

Auto deletion

Members stop working the instant ends_at passes. However, to avoid the member list from getting cluttered over time members are automatically deleted 1 day after their ends_at date.

If a member is deleted it won’t have access to anything regardless of any setting. You can un-delete a member by PATCHing it to set is_deleted to false.