Unkey.dev Elixir SDK for interacting with the platform programatically.
The package can be installed from Hex PM by adding unkey_elixir_sdk
to your list of dependencies in mix.exs
:
Note: This project uses Elixir version
1.13
.
def deps do
[
{:unkey_elixir_sdk, "~> 0.2.0"}
]
end
In order to start this package we can either start it under a supervision tree (most common).
The GenServer takes a map with two properties.
- token: Your Unkey Access token used to make requests. You can create one here required
- base_url: The base URL endpoint you will be hitting i.e.
https://api.unkey.dev/v1/keys
(optional).
children = [
{UnkeyElixirSdk, %{token: "yourunkeyapitoken"}}
]
# Now we start the supervisor with the children and a strategy
{:ok, pid} = Supervisor.start_link(children, strategy: :one_for_one)
# After started, we can query the supervisor for information
Supervisor.count_children(pid)
#=> %{active: 1, specs: 1, supervisors: 0, workers: 1}
You can also call the start_link
function instead.
{:ok, _pid} = UnkeyElixirSdk.start_link(%{token: "yourunkeyapitoken", base_url: "https://api.unkey.dev/v1/keys"})
Change: The revoke_key
function has been renamed to delete_key
.
The delete_key function now performs the same operation as revoke_key
.
Update your code to replace calls to revoke_key
withdelete_key
.
@spec create_key(map) :: map()
Creates an API key for your users. It takes a map with at least one property apiId
. Full list of properties can be found below or in the docs
Returns a map with the key
and keyId
.
UnkeyElixirSdk.create_key(%{"apiId" => "myapiid"})
# returns
%{"keyId" => "key_cm9vdCBvZiBnb29kXa", "key" => "xyz_AS5HDkXXPot2MMoPHD8jnL"}
UnkeyElixirSdk.create_key(%{
"apiId" => "myapiid",
"prefix" => "xyz",
"byteLength" => 16,
"ownerId" => "glamboyosa",
"meta" => %{
"hello" => "world"
},
"expires" => 1_686_941_966_471,
"ratelimit" => %{
"type" => "fast",
"limit" => 10,
"refillRate" => 1,
"refillInterval" => 1000
},
"remaining" => 5
})
# returns
%{"keyId" => "key_cm9vdCBvZiBnb29kXa", "key" => "xyz_AS5HDkXXPot2MMoPHD8jnL"}
@spec verify_key(binary, map()) :: map()
Verify a key from your users. You only need to send the api key from your user. Optionally, pass in a second param, a map with the key apiId
which sends the apiId
along.
Returns a map with whether the key is valid or not. Optionally sends ownerId
and meta
.
UnkeyElixirSdk.verify_key("xyz_AS5HDkXXPot2MMoPHD8jnL")
# returns
%{"valid" => true,
"ownerId" => "chronark",
"meta" => %{
"hello" => "world"
}}
UnkeyElixirSdk.verify_key("xyz_AS5HDkXXPot2MMoPHD8jnL", %{"apiId"=> "api_AS455efrefsfsf"})
# returns
%{"valid" => true,
"ownerId" => "chronark",
"meta" => %{
"hello" => "world"
}}
@spec update_key(binary(), map()) :: :ok Updates the configuration of a key
Takes in a key_id
argument and a map whose members are optional
but must have at most 1 member present.
%{
"name" => "my_new_key",
"ownerId" => "still_glamboyosa",
"meta" => %{
"hello" => "world"
},
"expires" => 1_686_941_966_471,
"ratelimit" => %{
"type" => "fast",
"limit" => 15,
"refillRate" => 2,
"refillInterval" => 500
},
"remaining" => 3
}
Returns :ok
UnkeyElixirSdk.update_key("key_cm9vdCBvZiBnb29kXa", %{
"name" => "my_new_key",
"ratelimit" => %{
"type" => "fast",
"limit" => 15,
"refillRate" => 2,
"refillInterval" => 500
},
"remaining" => 3
})
:ok
@spec update_remaining(map()) :: :ok
Updates the remaining
value for a specified key.
Takes in a map of the shape:
%{ "keyId": "key_123", "op": "increment", "value": 1 }
Where "op" is "increment" | "decrement" | "set" and value is the value you want to increase by or nil (unlimited)
Returns a map with the updated "remaining" value.
UnkeyElixirSdk.update_remaining(%{
"keyId": "key_123",
"op": "increment",
"value": 1
})
%{remaining: 100}
@spec delete_key(binary) :: :ok
Delete an api key for your users
Returns :ok
UnkeyElixirSdk.delete_key("key_cm9vdCBvZiBnb29kXa")
# returns
:ok
Documentation can be found at https://hexdocs.pm/unkey_elixir_sdk.