Add api token endpoints

examples/api_tokens_api.rb

@@ -7,3 +7,24 @@
 # List API tokens
 api_tokens.list
 # => [#<struct Mailtrap::ApiToken id=12345, name="My API Token", last_4_digits="x7k9", ..., token=nil>, ...]
+
+# Get a single API token (the `token` field is nil — the full value is only returned by create/reset)
+api_tokens.get(12_345)
+# => #<struct Mailtrap::ApiToken id=12345, name="My API Token", ..., token=nil>
+
+# Create a new API token. The full `token` value is returned ONLY once — store it securely.
+api_tokens.create(
+  name: 'My API Token',
+  resources: [
+    { resource_type: 'account', resource_id: account_id, access_level: 100 }
+  ]
+)
+# => #<struct Mailtrap::ApiToken id=12345, name="My API Token", ..., token="a1b2c3d4e5f6g7h8">
+
+# Reset a token — expires the old value (short grace period) and returns a new value once.
+api_tokens.reset(12_345)
+# => #<struct Mailtrap::ApiToken id=12345, ..., token="new-secret-value">
+
+# Permanently delete a token
+api_tokens.delete(12_345)
+# => nil

examples/permissions_api.rb

@@ -4,6 +4,16 @@
 client = Mailtrap::Client.new(api_key: 'your-api-key')
 permissions = Mailtrap::PermissionsAPI.new(account_id, client)
 
+# Get the recursive tree of resources the current token can access
+permissions.resources
+# => [
+#   #<struct Mailtrap::PermissionResource id=4001, name="My First Project", type="project",
+#     access_level=1, resources=[
+#       #<struct Mailtrap::PermissionResource id=3816, name="My First Inbox", type="inbox",
+#         access_level=100, resources=[]>
+#     ]>
+# ]
+
 # Bulk-update user/token permissions on an account access. Combine create/update with destroy:
 permissions.bulk_update(
   5142, # account_access_id

lib/mailtrap/api_tokens_api.rb

@@ -7,6 +7,8 @@ module Mailtrap
   class ApiTokensAPI
     include BaseAPI
 
+    self.supported_options = %i[name resources].freeze
+
     self.response_class = ApiToken
 
     # Lists API tokens visible to the current API token
@@ -16,6 +18,46 @@ def list
       base_list
     end
 
+    # Retrieves a single API token by ID
+    # @param token_id [Integer] The API token ID
+    # @return [ApiToken] API token object (the `token` field is nil — full value is only
+    #   returned by #create and #reset)
+    # @!macro api_errors
+    def get(token_id)
+      base_get(token_id)
+    end
+
+    # Creates a new API token. The full `token` value is returned ONLY ONCE — store it securely.
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name Display name for the token
+    # @option options [Array<Hash>] :resources Permissions to assign
+    #   - `{ resource_type:, resource_id:, access_level: }`
+    # @return [ApiToken] Created token (full `token` value populated)
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    # Expires the requested token and returns a new one with the same permissions.
+    # The old token stops working after a short grace period. The new `token` value is
+    # returned ONLY ONCE — store it securely
+    # @param token_id [Integer] The API token ID
+    # @return [ApiToken] New token (full `token` value populated)
+    # @!macro api_errors
+    def reset(token_id)
+      response = client.post("#{base_path}/#{token_id}/reset")
+      handle_response(response)
+    end
+
+    # Permanently deletes an API token
+    # @param token_id [Integer] The API token ID
+    # @return nil
+    # @!macro api_errors
+    def delete(token_id)
+      base_delete(token_id)
+    end
+
     private
 
     def base_path

lib/mailtrap/permission_resource.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for a node in the Permissions resources tree
+  # @attr_reader id [Integer] Resource ID
+  # @attr_reader name [String] Resource name
+  # @attr_reader type [String] Resource type (account, project, inbox, sending_domain, ...)
+  # @attr_reader access_level [Integer] The access level the current token has on this resource
+  # @attr_reader resources [Array<PermissionResource>] Nested child resources
+  PermissionResource = Struct.new(
+    :id,
+    :name,
+    :type,
+    :access_level,
+    :resources,
+    keyword_init: true
+  )
+end

lib/mailtrap/permissions_api.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'base_api'
+require_relative 'permission_resource'
 
 module Mailtrap
   class PermissionsAPI
@@ -20,10 +21,31 @@ def bulk_update(account_access_id, permissions)
       )
     end
 
+    # Returns the recursive tree of resources the current token can access.
+    # Each node carries the token's access_level and any nested child resources.
+    # @return [Array<PermissionResource>] Top-level resources, each with nested children
+    # @!macro api_errors
+    def resources
+      response = client.get("#{base_path}/permissions/resources")
+      build_resource_tree(response)
+    end
+
     private
 
     def base_path
       "/api/accounts/#{account_id}"
     end
+
+    def build_resource_tree(items)
+      items.map do |item|
+        PermissionResource.new(
+          id: item[:id],
+          name: item[:name],
+          type: item[:type],
+          access_level: item[:access_level],
+          resources: build_resource_tree(Array(item[:resources]))
+        )
+      end
+    end
   end
 end